# setup
Source: https://docs.treeship.dev/cli/setup

> Guided first-run — detect agents, draft Agent Cards, instrument, smoke verify.

## Usage

```bash
treeship setup [OPTIONS]
```

## What it does

One command for the typical first-run flow. Composes existing primitives — agent discovery, the Agent Card store, the Harness Manager, the smoke session — into a single orchestrated path.

1. **Detect agents** on this machine (Claude Code, Cursor, Cline, Codex, Hermes, OpenClaw, generic MCP, shell-wrap, NinjaTech).
2. **Draft an Agent Card** for each detected agent. Idempotent on re-run — re-running setup against the same machine doesn't double-write cards.
3. **Confirm** before modifying any agent's config files. Non-interactive without `--yes` defaults to a safe "no" — CI invocations don't touch user configs without permission.
4. **Instrument** the detected agents (Treeship MCP server, hooks, skill files), through the same path `treeship add` uses.
5. **Smoke session** — run a real session round-trip (`init → session start → wrap → session close → package verify`) inside an isolated tmpdir to prove Treeship's pipeline works end-to-end on this machine.
6. **Promote cards** to `Active` and **harnesses** to `Instrumented` on smoke success. *Never* to `Verified` — that status is reserved for per-harness smokes that prove specific capture signals.

<Callout type="info">
  The smoke pass proves Treeship's pipeline works, not that any specific harness's capture path fires. Card status `Verified` only happens when a harness-specific smoke run proves each capture signal individually. See [Harnesses](/concepts/harnesses) for the full status ladder.
</Callout>

## Examples

```bash
# Default — interactive, prompts before writing configs
treeship setup
```

```bash
# Non-interactive: instrument all detected agents
treeship setup --yes
```

```bash
# Cards + instrumentation only, skip the smoke session
treeship setup --skip-smoke
```

```bash
# Cards only — discover and draft, never modify any config
treeship setup --no-instrument
```

```bash
# Machine-readable for AI agents and CI orchestration
treeship setup --yes --format json
```

## Sample output

```
✓ detected 3 agents on this machine
  - claude-code @ ~/Library/Application Support/Claude/...   confidence: high
  - cursor      @ ~/.cursor/extensions/...                   confidence: high
  - hermes      @ ~/.openclaw/skills/treeship.md             confidence: medium

instrument all 3? (y/N) y

✓ instrumented claude-code (Treeship MCP server)
✓ instrumented cursor      (Treeship MCP server)
✓ instrumented hermes      (skill file)

running smoke session...
✓ smoke session passed   (5 events, 1 wrap, package verifies)

cards promoted: 3 (Draft -> Active)
harnesses promoted: 3 (Detected -> Instrumented)

next: run a real session through each agent to prove its specific capture
signals. After that, harness status flips Instrumented -> Verified.
```

## Options

| Option            | Description                                                                                                               |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `--yes`           | Skip the confirmation prompt; instrument every detected agent.                                                            |
| `--skip-smoke`    | Skip the smoke verification pass after instrumentation. Cards still promote `Draft → Active`; harnesses stay `Available`. |
| `--no-instrument` | Detect + draft cards only. Never modify any agent config files.                                                           |
| `--format <fmt>`  | `text` (default) or `json`. The JSON shape is stable for AI agents and orchestration.                                     |
| `--config <path>` | Config file path (default `~/.treeship/config.json`).                                                                     |
| `--quiet`         | Suppress all output except errors.                                                                                        |
| `--no-color`      | Disable color output.                                                                                                     |

## Idempotency

Re-running `setup` against an already-set-up machine:

* Re-runs discovery; new agents detected since the last run get fresh `Draft` cards.
* Existing cards are *merged*, not overwritten. Approved cards stay `Active`.
* Instrumentation is idempotent — if an agent's config already has the Treeship entry, `add` skips it.
* The smoke session always runs in a fresh tmpdir, so it never pollutes the workspace journal.

## What gets written

* `~/.treeship/agents/<id>.json` — one Agent Card per detected agent
* `~/.treeship/harnesses/<id>.json` — one Harness State per detected agent
* agent-specific config files when `--no-instrument` is **not** set:
  * Claude Code / Cursor / Cline: an MCP server entry pointing at `@treeship/mcp`
  * Codex: an MCP entry in `~/.codex/config.toml`
  * Hermes / OpenClaw: a skill file at the agent's skills directory

If setup fails partway, the smoke session leaves nothing behind (isolated tmpdir). Card and harness state writes are append-only and survive a partial run.

## Agent-mode JSON output

```bash
treeship setup --yes --format json
```

Today (v0.9.10), `setup --format json` returns an empty JSON object on completion (`{}`) — the orchestration result lives in the human-readable text output. The structured agent-mode shape that surfaces detected/instrumented/smoke/cards/harnesses counts is part of the **Agent-Native Bootstrap** roadmap and lands in a later v0.10.x release. Until then, if an AI agent needs to inspect what setup produced, it should call the per-component commands afterward:

```bash
treeship add --discover --format json   # what's on the machine
treeship harness list --format json     # which harnesses are wired
# (treeship agents list --format json   # — currently {}; see /cli/agents)
```

`treeship harness list --format json` already returns a rich, stable shape today and is the most useful agent-readable touchpoint until `setup`'s shape stabilizes.

## See also

* [add](/cli/add) — the underlying instrumenter setup orchestrates
* [agents](/cli/agents) — manage the resulting Agent Card store
* [harness](/cli/harness) — inspect harness state and run per-harness smokes
* [Agent Cards](/concepts/agent-cards) — the trust object setup produces
* [Harnesses](/concepts/harnesses) — the attachment surface setup wires