> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents-squads.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Complete command reference for squads-cli v0.9.0 — generated from the live command registry

This reference is generated from the CLI's own command registry, so it always
matches the installed version. Verify yours with `squads version`.

```bash theme={null}
npm install -g squads-cli
```

## squads init

Plant the seed: create manager agent, CLI skill, and starter squads

```bash theme={null}
squads init
```

| Option                      | Description                                                                 |
| --------------------------- | --------------------------------------------------------------------------- |
| `-p, --provider <provider>` | LLM provider (claude, gemini, openai, ollama, none)                         |
| `--pack <packs...>`         | Additional squad packs to install (engineering, marketing, operations, all) |
| `--skip-infra`              | Skip infrastructure setup prompt                                            |
| `--force`                   | Skip requirement checks (for CI/testing)                                    |
| `-y, --yes`                 | Accept all defaults (non-interactive mode)                                  |
| `-q, --quick`               | Quick init - create files only, skip interactive prompts                    |

## squads run

Run a squad or agent (no target lists squads). Use --org to run all squads as one coordinated cycle.

```bash theme={null}
squads run [target] [agent]
```

| Option                     | Description                                                                        |
| -------------------------- | ---------------------------------------------------------------------------------- |
| `-v, --verbose`            | Verbose output                                                                     |
| `-d, --dry-run`            | Show what would be run without executing                                           |
| `-a, --agent <agent>`      | Run specific agent within squad                                                    |
| `-t, --timeout <minutes>`  | Per-agent execution timeout in minutes (default: 15)                               |
| `-p, --parallel`           | Run all agents in parallel (N tmux sessions)                                       |
| `-l, --lead`               | Lead mode: single orchestrator using Task tool for parallelization                 |
| `-b, --background`         | Run agent in background (detached process)                                         |
| `-w, --watch`              | Run in background but tail the log for visibility                                  |
| `--use-api`                | Use API credits instead of subscription                                            |
| `--effort <level>`         | Effort level: high, medium, low (default: from SQUAD.md or high)                   |
| `--skills <skills...>`     | Skills to load (skill IDs or local paths)                                          |
| `--provider <provider>`    | LLM provider: anthropic, google, openai, mistral, xai, aider, ollama               |
| `--model <model>`          | Model to use (e.g., opus, sonnet, haiku, gemini-2.5-flash, gpt-4o)                 |
| `--trigger <type>`         | Trigger source: manual, scheduled, event, smart (default: manual)                  |
| `--cloud`                  | Dispatch execution to cloud worker via API (requires squads login)                 |
| `--task <directive>`       | Founder directive for conversation mode (replaces lead briefing)                   |
| `--max-turns <n>`          | Max conversation turns (default: 20) (default: `20`)                               |
| `--cost-ceiling <usd>`     | Cost ceiling in USD (default: 25) (default: `25`)                                  |
| `--no-verify`              | Skip post-execution verification (Ralph loop)                                      |
| `--execute`                | Explicitly execute agents (default for run \<target>)                              |
| `-j, --json`               | Output as JSON                                                                     |
| `-i, --interval <minutes>` | Autopilot: minutes between cycles (default: `30`)                                  |
| `--max-parallel <count>`   | Autopilot: max parallel squad loops (default: `2`)                                 |
| `--budget <usd>`           | Autopilot: daily budget cap (\$) (default: `0`)                                    |
| `--once`                   | Autopilot: run one cycle then exit                                                 |
| `--phased`                 | Autopilot: use dependency-based phase ordering (from SQUAD.md depends\_on)         |
| `--no-eval`                | Skip post-run COO evaluation                                                       |
| `--org`                    | Run all squads as a coordinated org cycle (scan → plan → execute → report)         |
| `--force`                  | Force re-run squads that already completed today; bypasses pause enforcement       |
| `--resume`                 | Resume org cycle from where quota stopped it                                       |
| `--wait-for-quota`         | Org cycle: on quota cap, poll until the session window reopens instead of stopping |
| `-y, --yes`                | Skip the org-run cost confirmation (for deliberate/non-interactive triggers)       |
| `--focus <mode>`           | Cycle focus: create, resolve, review, ship, research, cost (default: create)       |

## squads pause

Pause a squad — run/org/cron dispatch will refuse until resumed

```bash theme={null}
squads pause <squad>
```

| Option                | Description        |
| --------------------- | ------------------ |
| `-r, --reason <text>` | Reason for pausing |
| `-j, --json`          | Output as JSON     |

## squads resume

Resume a paused squad

```bash theme={null}
squads resume <squad>
```

| Option       | Description    |
| ------------ | -------------- |
| `-j, --json` | Output as JSON |

## squads env

View squad execution environment (MCP, skills, model, budget)

```bash theme={null}
squads env
```

### squads env show

Show execution environment for a squad

```bash theme={null}
squads env show <squad>
```

| Option   | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### squads env prompt

Output ready-to-use prompt for Claude Code execution

```bash theme={null}
squads env prompt <squad>
```

| Option                | Description                 |
| --------------------- | --------------------------- |
| `-a, --agent <agent>` | Agent to execute (required) |
| `--json`              | Output as JSON              |

## squads dashboard

Show dashboards. Use "squads dash" for overview, "squads dash \<name>" for specific dashboard, "squads dash --list" to see all.

```bash theme={null}
squads dashboard [name]
```

Aliases: `squads dash`

| Option          | Description                                    |
| --------------- | ---------------------------------------------- |
| `-v, --verbose` | Show additional details                        |
| `-c, --ceo`     | Executive summary with priorities and blockers |
| `-f, --full`    | Include GitHub PR/issue stats (slower, \~30s)  |
| `-l, --list`    | List available declarative dashboards          |
| `--view <view>` | Render specific view from dashboard            |
| `-j, --json`    | Output as JSON                                 |

## squads status

Show squad status and state

```bash theme={null}
squads status [squad]
```

| Option          | Description          |
| --------------- | -------------------- |
| `-v, --verbose` | Show detailed status |
| `-j, --json`    | Output as JSON       |

## squads usage

Show local cost/token usage (today, rolling window, by squad)

```bash theme={null}
squads usage
```

| Option                 | Description                                                                    |
| ---------------------- | ------------------------------------------------------------------------------ |
| `-w, --window <hours>` | Rolling-window size in hours (default: `5`)                                    |
| `--all-claude`         | Include ALL Claude Code sessions on this machine, not just this project (#960) |
| `--json`               | Output as JSON                                                                 |

## squads doctor

Check local tools, auth, and project readiness

```bash theme={null}
squads doctor
```

| Option          | Description                           |
| --------------- | ------------------------------------- |
| `-v, --verbose` | Show install hints and optional tools |

## squads goal

Manage squad goals

```bash theme={null}
squads goal
```

### squads goal set

Set a goal for a squad

```bash theme={null}
squads goal set <squad> <description>
```

| Option                      | Description      |
| --------------------------- | ---------------- |
| `-m, --metric <metrics...>` | Metrics to track |

### squads goal list

List goals for squad(s)

```bash theme={null}
squads goal list [squad]
```

| Option       | Description              |
| ------------ | ------------------------ |
| `-a, --all`  | Show completed goals too |
| `-j, --json` | Output as JSON           |

### squads goal complete

Mark a goal as completed

```bash theme={null}
squads goal complete <squad> <index>
```

### squads goal progress

Update goal progress

```bash theme={null}
squads goal progress <squad> <index> <progress>
```

## squads feedback

Record and view execution feedback

```bash theme={null}
squads feedback
```

### squads feedback add

Add feedback for last execution (rating 1-5)

```bash theme={null}
squads feedback add <squad> <rating> <feedback>
```

| Option                          | Description          |
| ------------------------------- | -------------------- |
| `-l, --learning <learnings...>` | Learnings to extract |

### squads feedback show

Show feedback history

```bash theme={null}
squads feedback show <squad>
```

| Option            | Description                              |
| ----------------- | ---------------------------------------- |
| `-n, --limit <n>` | Number of entries to show (default: `5`) |

### squads feedback stats

Show feedback summary across all squads

```bash theme={null}
squads feedback stats
```

## squads memory

Query and manage squad memory

```bash theme={null}
squads memory
```

### squads memory query

Search across all squad memory

```bash theme={null}
squads memory query <query>
```

| Option                | Description                    |
| --------------------- | ------------------------------ |
| `-s, --squad <squad>` | Limit search to specific squad |
| `-a, --agent <agent>` | Limit search to specific agent |

### squads memory read

Show memory for a squad

```bash theme={null}
squads memory read <squad>
```

### squads memory write

Add to squad memory

```bash theme={null}
squads memory write <squad> <content>
```

| Option                | Description                                                    |
| --------------------- | -------------------------------------------------------------- |
| `-a, --agent <agent>` | Specific agent (default: squad-lead)                           |
| `-t, --type <type>`   | Memory type: state, learnings, feedback (default: `learnings`) |

### squads memory list

List all memory entries

```bash theme={null}
squads memory list
```

### squads memory sync

Sync memory from git: pull remote changes, process commits, optionally push to Postgres

```bash theme={null}
squads memory sync
```

| Option          | Description                                                    |
| --------------- | -------------------------------------------------------------- |
| `-v, --verbose` | Show detailed commit info                                      |
| `-p, --push`    | Push local memory changes to remote after sync                 |
| `--no-pull`     | Skip pulling from remote                                       |
| `--postgres`    | Sync cycle data (goals, feedback, KPIs, learnings) to Postgres |
| `--dimensions`  | Sync squad/agent definitions to Postgres dim tables            |
| `--learnings`   | Sync learnings.md files to Postgres                            |
| `--auto-learn`  | Auto-generate learnings from session commits                   |

### squads memory search

Search stored conversations (requires authentication: squads login)

```bash theme={null}
squads memory search <query>
```

| Option                          | Description                               |
| ------------------------------- | ----------------------------------------- |
| `-l, --limit <limit>`           | Number of results (default: `10`)         |
| `-r, --role <role>`             | Filter by role: user, assistant, thinking |
| `-i, --importance <importance>` | Filter by importance: low, normal, high   |

### squads memory extract

Extract memories from recent conversations into Engram

```bash theme={null}
squads memory extract
```

| Option                    | Description                               |
| ------------------------- | ----------------------------------------- |
| `-s, --session <session>` | Extract specific session only             |
| `-h, --hours <hours>`     | Look back period in hours (default: `24`) |
| `-d, --dry-run`           | Preview without sending to Engram         |

## squads login

Log in to Squads (Pro & Enterprise)

```bash theme={null}
squads login
```

## squads logout

Log out from Squads

```bash theme={null}
squads logout
```

## squads whoami

Show current logged in user

```bash theme={null}
squads whoami
```

## squads contract

Agent Contracts — the governed definition of what each agent may do

```bash theme={null}
squads contract
```

### squads contract validate

Derive + validate every agent contract; non-zero exit on any violation

```bash theme={null}
squads contract validate
```

| Option           | Description             |
| ---------------- | ----------------------- |
| `--squad <name>` | validate a single squad |
| `--json`         | machine-readable output |

## squads providers

Show available LLM CLI providers (claude, gemini, codex, etc.)

```bash theme={null}
squads providers
```

| Option       | Description    |
| ------------ | -------------- |
| `-j, --json` | Output as JSON |

## squads update

Check for and install updates

```bash theme={null}
squads update
```

| Option        | Description                           |
| ------------- | ------------------------------------- |
| `-y, --yes`   | Auto-confirm update without prompting |
| `-c, --check` | Check for updates without installing  |

## squads version

Show version information

```bash theme={null}
squads version
```

## squads runs

List live background agent runs (pid-file inventory)

```bash theme={null}
squads runs
```

| Option               | Description                                                                       |
| -------------------- | --------------------------------------------------------------------------------- |
| `--json`             | Output as JSON                                                                    |
| `--clean`            | Remove stale pid files; salvage crashed runs (harvest + record)                   |
| `--replay <execId>`  | Re-render a finished run's activity feed from its recorded events                 |
| `--report <execId>`  | Context-economy report for a finished run (per-agent cost, cache hits, per-layer) |
| `--outcome <execId>` | Did the run's output land? Resolve its PRs/issues live: merged/open/closed        |

## squads inbox

Everything waiting on a human decision — list, or approve/reject/defer \<id>

```bash theme={null}
squads inbox [action] [id]
```

| Option            | Description                                                                                                |
| ----------------- | ---------------------------------------------------------------------------------------------------------- |
| `--json`          | Output as JSON                                                                                             |
| `--reason <text>` | Why (required for reject; written through to squads feedback)                                              |
| `--days <n>`      | Defer window in days (default 7)                                                                           |
| `--by <actor>`    | Who decided (default: squads login email, else OS user) — for bridges executing another surface’s decision |

## squads propose

Draft one complementary deliverable as a reviewable proposal branch (ambient, bounded, local-only)

```bash theme={null}
squads propose
```

| Option                 | Description                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------- |
| `--squad <name>`       | Squad to dispatch (default: keyword-overlap heuristic against BUSINESS\_BRIEF/README/package.json) |
| `--cost-ceiling <usd>` | Cost ceiling in USD (default: 5)                                                                   |
| `--json`               | Output as JSON                                                                                     |

## squads scoreboard

Executor quality-per-cost ranking from real runs (read-only, provenance-labeled)

```bash theme={null}
squads scoreboard
```

| Option       | Description                                                            |
| ------------ | ---------------------------------------------------------------------- |
| `--json`     | Output as JSON                                                         |
| `--days <n>` | Window in days (default 30)                                            |
| `--resolve`  | Check recent PR artifacts live against GitHub for landed-rate (slower) |

## squads kill

Stop a background run gracefully (pid, squad, or squad/agent)

```bash theme={null}
squads kill [target]
```

| Option  | Description                   |
| ------- | ----------------------------- |
| `--all` | Stop all live background runs |

## squads commands

List the live command tree (machine-readable with --json)

```bash theme={null}
squads commands
```

| Option   | Description                     |
| -------- | ------------------------------- |
| `--json` | Output as JSON                  |
| `--all`  | Include hidden/removed commands |