---
title: setup
description: Install bundled agent skills and write MCP registration settings.
canonical_url: https://orchestor.io/docs/en/cli/setup
markdown_url: https://orchestor.io/docs/en/cli/setup.md
contentType: reference
---

# setup

`orc setup` installs skills bundled with the CLI into directories read by agents, checks installation state, and removes installed links. It also has a local MCP registration writer.

Skill installation operates on local files. Use the [hosted MCP workflow](https://orchestor.io/docs/cli/workflows/agent-connect.md) for a working MCP connection. `setup mcp` writes a registration invoking `orc mcp serve`, but that executable command is not provided.

## Usage

```bash title="terminal"
orc setup skills --agent codex
```

*Install skills into the project-level Codex directory.*

## Subcommands

### `skills`

Copies embedded skills into the canonical `.agents/skills` directory and links target agent skill directories to that copy. Windows uses junctions; if linking fails, the command copies the same content. `--status` checks installed, missing, broken, and version-drift states.

```bash title="terminal"
orc setup skills [options]
```

#### Unique options

##### `--status`

List installed / missing / broken / version-drift state

Type: `boolean`. Optional.

```bash title="terminal"
orc setup skills --status
```

##### `--uninstall`

Remove installed Orchestor skill symlinks from agent skill paths

Type: `boolean`. Optional.

```bash title="terminal"
orc setup skills --uninstall
```

##### `--force`

Replace existing symlinks without prompting; non-symlink paths are skipped

Type: `boolean`. Optional.

```bash title="terminal"
orc setup skills --force
```

##### `--only`

Comma-separated skill slugs to install (default: all bundled skills)

Type: `string`. Optional.

```bash title="terminal"
orc setup skills --only <value>
```

##### `--agent`

Target one agent runtime (for example: codex or claude-code)

Type: `string`. Optional.

```bash title="terminal"
orc setup skills --agent <value>
```

##### `--all`

Target every supported agent skill directory

Type: `boolean`. Optional.

```bash title="terminal"
orc setup skills --all
```

##### `--global`

Install to user-level agent directories instead of the current project

Type: `boolean`. Optional.

```bash title="terminal"
orc setup skills --global
```

### `mcp`

`--target project` (the default) writes an Orchestor local server registration in `.mcp.json`; `--target claude-desktop` writes Claude Desktop configuration. The registered `orc mcp serve` command is unavailable, so writing this configuration alone does not complete a connection.

```bash title="terminal"
orc setup mcp [options]
```

#### Unique options

##### `--target`

Config target: project (.mcp.json) or claude-desktop

Type: `string`. Optional.

```bash title="terminal"
orc setup mcp --target <value>
```

## Examples

### Check installation state.

```bash title="terminal"
orc setup skills --agent codex --status
```

*Check installation state.*

### Install for all supported agents at user level.

```bash title="terminal"
orc setup skills --all --global
```

*Install for all supported agents at user level.*

### Remove installed Codex links.

```bash title="terminal"
orc setup skills --agent codex --uninstall
```

*Remove installed Codex links.*

## Installation targets and removal

By default, the canonical copy is stored at user-level `~/.agents/skills`, targeting the user-level Claude Code directory. `--agent` or `--all` targets project-level directories; add `--global` for user-level installation. `--only` accepts comma-separated skill slugs and defaults to all bundled skills.

`--force` replaces existing symlinks without prompting and skips regular paths. `--uninstall` removes only Orchestor skill symlinks in target agent directories, leaving the canonical copy and regular directories intact.

## Global Options

The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc setup`:

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#help)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation)
- [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing)
- [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#read-only-mode)
- [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#untrusted-content-wrapping)

For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md).

---

[Documentation index](https://orchestor.io/docs/llms.txt)