CLI Reference - Agents Squads

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

npm install -g squads-cli

squads init

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

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 add

Add a new squad with directory structure and starter files

squads add <name>

Option	Description
`-d, --description <text>`	Squad mission (one sentence)
`-g, --goal <text>`	First goal for the squad
`-m, --model <model>`	Default model (default: sonnet)
`-f, --force`	Overwrite existing squad
`-y, --yes`	Accept all defaults (non-interactive)
`-r, --repo`	Create a GitHub repository for the squad
`-o, --org <org>`	GitHub organization for —repo (default: detected from git remote)

squads run

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

squads run [target]

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
`--resume`	Resume org cycle from where quota stopped it
`-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 list

List squads (alias for: squads status)

squads list

squads orchestrate

Run squad with lead agent orchestration

squads orchestrate <squad>

Option	Description
`-f, --foreground`	Run lead in foreground (interactive)
`-v, --verbose`	Show detailed output and watch events
`-t, --timeout <minutes>`	Maximum runtime in minutes (default: `60`)

squads env

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

squads env

squads env show

Show execution environment for a squad

squads env show <squad>

Option	Description
`--json`	Output as JSON

squads env prompt

Output ready-to-use prompt for Claude Code execution

squads env prompt <squad>

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

squads exec

View execution history and statistics

squads exec

squads exec list

List recent executions

squads exec list

Option	Description
`-s, --squad <squad>`	Filter by squad
`-a, --agent <agent>`	Filter by agent
`--status <status>`	Filter by status (running, completed, failed)
`-n, --limit <n>`	Number of executions to show (default: `20`)
`--json`	Output as JSON

squads exec show

Show execution details

squads exec show <id>

Option	Description
`--json`	Output as JSON

squads exec stats

Show execution statistics

squads exec stats

Option	Description
`-s, --squad <squad>`	Filter by squad
`--json`	Output as JSON

squads log

Show run history with timestamps, duration, and status

squads log

Option	Description
`-s, --squad <squad>`	Filter by squad
`-a, --agent <agent>`	Filter by agent
`-n, --limit <n>`	Number of runs to show (default: 20) (default: `20`)
`--since <date>`	Show runs since date (e.g. 7d, 2026-04-01)
`-j, --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.

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

squads status [squad]

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

squads context

Get business context for alignment: goals, memory, costs, activity

squads context

Aliases: squads feed

Option	Description
`-s, --squad <squad>`	Focus on specific squad
`-t, --topic <topic>`	Search memory for relevant context
`-a, --agent`	Output JSON for agent consumption
`-j, --json`	Output as JSON (alias for —agent)
`-v, --verbose`	Show additional details

squads cost

Show cost summary (today, week, by squad)

squads cost

Option	Description
`-s, --squad <squad>`	Filter to specific squad
`--json`	Output as JSON

squads budget

Check budget status for a squad

squads budget <squad>

Option	Description
`--json`	Output as JSON

squads usage

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

squads usage

Option	Description
`-w, --window <hours>`	Rolling-window size in hours (default: `5`)
`--json`	Output as JSON

squads health

Quick health check for all infrastructure services

squads health

Option	Description
`-v, --verbose`	Show optional services

squads doctor

Check local tools, auth, and project readiness

squads doctor

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

squads history

Show recent agent execution history

squads history

Option	Description
`-d, --days <days>`	Days to look back (default: `7`)
`-s, --squad <squad>`	Filter by squad
`-v, --verbose`	Show cost and token details
`-j, --json`	Output as JSON

squads results

Show squad results: git activity + KPI goals vs actuals

squads results [squad]

Option	Description
`-d, --days <days>`	Days to look back (default: `7`)
`-v, --verbose`	Show detailed KPIs per goal

squads goal

Manage squad goals

squads goal

squads goal set

Set a goal for a squad

squads goal set <squad> <description>

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

squads goal list

List goals for squad(s)

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

squads goal complete <squad> <index>

squads goal progress

Update goal progress

squads goal progress <squad> <index> <progress>

squads kpi

Track and analyze squad KPIs (defined in SQUAD.md frontmatter)

squads kpi

squads kpi list

List all KPIs across squads

squads kpi list

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

squads kpi show

Show KPI status for a squad

squads kpi show <squad>

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

squads kpi record

Record a KPI value

squads kpi record <squad> <kpi> <value>

Option	Description
`-n, --note <note>`	Add a note to the record
`-j, --json`	Output as JSON

squads kpi trend

Show KPI trend over time

squads kpi trend <squad> <kpi>

Option	Description
`-p, --periods <n>`	Number of periods to show (default: `7`)
`-j, --json`	Output as JSON

squads kpi insights

Generate insights from KPI data

squads kpi insights [squad]

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

squads progress

Track active and completed agent tasks

squads progress

Option	Description
`-v, --verbose`	Show more activity

squads progress start

squads progress start <squad> <description>

squads progress complete

Mark a task as completed

squads progress complete <taskId>

Option	Description
`-f, --failed`	Mark as failed instead

squads feedback

Record and view execution feedback

squads feedback

squads feedback add

Add feedback for last execution (rating 1-5)

squads feedback add <squad> <rating> <feedback>

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

squads feedback show

Show feedback history

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

squads feedback stats

squads autonomy

Show autonomy score and confidence metrics

squads autonomy

Option	Description
`-s, --squad <squad>`	Filter by squad
`-p, --period <period>`	Time period: today, week, month (default: `today`)
`-j, --json`	Output as JSON

squads autopilot

[deprecated] Use “squads run” instead — autopilot mode when no target given

squads autopilot

Aliases: squads daemon

Option	Description
`-i, --interval <minutes>`	Minutes between cycles (default: `30`)
`-p, --parallel <count>`	Max parallel agent runs (default: `2`)
`-b, --budget <dollars>`	Max daily spend in dollars (0 = unlimited/subscription) (default: `0`)
`--once`	Run one cycle and exit
`--dry-run`	Show what would run without dispatching
`-v, --verbose`	Show detailed scoring

squads stats

Show agent outcome scorecards: merge rate, waste, cost per outcome

squads stats [squad]

Option	Description
`-p, --period <period>`	Time period: 7d or 30d (default: `7d`)
`-j, --json`	Output as JSON

squads memory

Query and manage squad memory

squads memory

squads memory query

Search across all squad memory

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

squads memory read <squad>

squads memory write

Add to squad memory

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

squads memory list

squads memory sync

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

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)

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

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 learn

Capture a learning for future sessions

squads learn <insight>

Option	Description
`-s, --squad <squad>`	Squad to associate learning with
`-c, --category <category>`	Category: success, failure, pattern, tip
`-t, --tags <tags>`	Comma-separated tags
`--context <context>`	Additional context

squads learnings

View and search learnings

squads learnings

squads learnings show

Show learnings for a squad

squads learnings show <squad>

Option	Description
`-n, --limit <n>`	Number to show (default: `10`)
`-c, --category <category>`	Filter by category
`--tag <tag>`	Filter by tag

squads learnings search

Search learnings across all squads

squads learnings search <query>

Option	Description
`-n, --limit <n>`	Max results (default: `10`)

squads sync

Git memory synchronization (Postgres sync optional)

squads 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 to Postgres

squads trigger

Manage smart triggers

squads trigger

squads trigger list

List triggers

squads trigger list [squad]

squads trigger sync

Sync SQUAD.md triggers to scheduler

squads trigger sync

squads trigger fire

Manually fire a trigger

squads trigger fire <name>

squads trigger enable

Enable a trigger

squads trigger enable <name>

squads trigger disable

Disable a trigger

squads trigger disable <name>

squads trigger status

Show scheduler status

squads trigger status

squads approval

Manage approval requests for agent actions

squads approval

squads approval send

Send approval request to Slack

squads approval send <type>

Option	Description
`-t, --title <title>`	Approval title
`-d, --description <desc>`	Detailed description
`-s, --squad <squad>`	Squad name
`-a, --agent <agent>`	Agent name
`-p, --priority <n>`	Priority 1-10 (1=urgent) (default: `5`)
`-e, --expires-in <time>`	Expiration time (24h, 1h, 30m) (default: `24h`)
`-j, --json <json>`	Full payload as JSON (use - for stdin)

squads approval list

List approvals

squads approval list

Option	Description
`--pending`	Only show pending approvals (default: `true`)
`-s, --squad <squad>`	Filter by squad
`-j, --json`	Output as JSON

squads approval check

Check approval status

squads approval check <id>

Option	Description
`-w, --wait`	Wait for decision (polls every 5s)
`-t, --timeout <minutes>`	Wait timeout in minutes (default: `60`)

squads approval cancel

Cancel pending approval

squads approval cancel <id>

squads autonomous

Local scheduling daemon for autonomous agent execution

squads autonomous

Aliases: squads auto

squads autonomous start

Start the scheduling daemon

squads autonomous start

squads autonomous stop

Stop the scheduling daemon

squads autonomous stop

squads autonomous status

Show daemon status, running agents, and next runs

squads autonomous status

squads autonomous pause

Pause the daemon (e.g. quota exhausted)

squads autonomous pause [reason]

squads autonomous resume

Resume a paused daemon

squads autonomous resume

squads sessions

Show active Claude Code sessions across squads

squads sessions

Option	Description
`-v, --verbose`	Show session details
`-j, --json`	Output as JSON

squads sessions history

Show session history and statistics

squads sessions history

Option	Description
`-d, --days <days>`	Days of history to show (default: `7`)
`-s, --squad <squad>`	Filter by squad
`-j, --json`	Output as JSON

squads sessions summary

Show pretty session summary (auto-detects current session or pass JSON)

squads sessions summary

Option	Description
`-d, --data <json>`	JSON data for summary (overrides auto-detection)
`-f, --file <path>`	Path to JSON file with summary data
`-j, --json`	Output as JSON instead of pretty format

squads session

Manage current session lifecycle

squads session

squads session start

squads session start

Option	Description
`-s, --squad <squad>`	Override squad detection
`-q, --quiet`	Suppress output

squads session stop

End current session

squads session stop

Option	Description
`-q, --quiet`	Suppress output

squads session heartbeat

Update session heartbeat

squads session heartbeat

Option	Description
`-q, --quiet`	Suppress output

squads detect-squad

Detect current squad based on cwd (for use in hooks)

squads detect-squad

squads login

squads logout

Log out from Squads

squads logout

squads whoami

Show current logged in user

squads whoami

squads eval

Evaluate agent readiness for deployment (e.g., squads eval company/coo)

squads eval <target>

Option	Description
`-j, --json`	Output as JSON
`-v, --verbose`	Show detailed scoring info

squads deploy

Deploy agents to the Squads platform

squads deploy

Option	Description
`-n, --dry-run`	Show what would be deployed without pushing
`-s, --squad <squad>`	Deploy only a specific squad
`-v, --verbose`	Show detailed agent and trigger info

squads deploy status

Show current platform deployment status

squads deploy status

squads deploy pull

Pull execution data and learnings from platform

squads deploy pull

Option	Description
`-v, --verbose`	Show detailed execution info

squads cognition

Business cognition engine — beliefs, decisions, reflections

squads cognition

squads cognition brief

Executive summary: hot beliefs + recent signals + pending decisions

squads cognition brief

squads cognition beliefs

Display world model beliefs

squads cognition beliefs

Option	Description
`-d, --domain <domain>`	Filter by domain (revenue/product/operations/market/team)
`-j, --json`	Output as JSON

squads cognition decisions

Decision journal with outcome scores

squads cognition decisions

Option	Description
`-e, --evaluated`	Only show evaluated decisions
`-j, --json`	Output as JSON

squads cognition reflect

Trigger meta-cognition reflection

squads cognition reflect

Option	Description
`-s, --scope <scope>`	Reflection scope (business, squad:X, agent:X) (default: `business`)

squads contract

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

squads contract

squads contract validate

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

squads contract validate

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

squads catalog

Service catalog — browse, inspect, and validate services

squads catalog

squads catalog list

List all services in the catalog

squads catalog list

Option	Description
`--type <type>`	Filter by type (product, domain)
`--json`	Output as JSON

squads catalog show

Show detailed info for a service

squads catalog show <service>

Option	Description
`--json`	Output as JSON

squads catalog check

Run scorecard checks for a service (or all)

squads catalog check [service]

Option	Description
`--json`	Output as JSON

squads release

Release management — pre-deploy checks and status

squads release

squads release pre-check

Validate dependencies and health before deploying a service

squads release pre-check <service>

Option	Description
`--skip-health`	Skip health endpoint checks

squads obs

Observability — execution history, token costs, and trends

squads obs

squads obs history

Show execution history with tokens and cost

squads obs history

Option	Description
`-s, --squad <squad>`	Filter by squad
`-a, --agent <agent>`	Filter by agent
`-n, --limit <n>`	Number of records (default: `20`)
`--since <date>`	Since date (ISO or relative: 1d, 7d, 30d)
`--json`	Output as JSON

squads obs cost

Show token spend summary

squads obs cost

Option	Description
`-p, --period <period>`	Time period: today, 7d, 30d, all (default: `7d`)
`--json`	Output as JSON

squads obs sync

Backfill JSONL execution data to Postgres (Tier 2)

squads obs sync

Option	Description
`--dry-run`	Show what would be synced without sending

squads tier

Show active infrastructure tier and available services

squads tier

Option	Description
`--json`	Output as JSON

squads services

Manage local Docker services for your project

squads services

squads services up

Start local services (Docker required)

squads services up

Option	Description
`--file <path>`	Path to docker-compose.yml

squads services down

Stop local services

squads services down

Option	Description
`--file <path>`	Path to docker-compose.yml

squads services status

Show running Docker containers and health

squads services status

Option	Description
`--file <path>`	Path to docker-compose.yml

squads goals

Dashboard of all squad goals — status at a glance

squads goals

Option	Description
`-s, --squad <squad>`	Show goals for a specific squad
`--json`	Output as JSON

squads credentials

Manage per-squad GCP service accounts and credentials

squads credentials

squads credentials create

Create a service account and key for a squad

squads credentials create <squad>

Option	Description
`--force`	Recreate even if credential exists

squads credentials create-all

Create credentials for all squads with GCP config in SQUAD.md

squads credentials create-all

Option	Description
`--force`	Recreate even if credentials exist

squads credentials rotate

Rotate a squad credential (create new key, delete old)

squads credentials rotate <squad>

squads credentials list

List all squad credentials and their status

squads credentials list

squads credentials revoke

Delete a squad service account and all keys

squads credentials revoke <squad>

squads review

Post-cycle evaluation — goals, costs, blockers, founder actions

squads review

Option	Description
`-s, --squad <squad>`	Detail view for a specific squad
`--since <period>`	Look back period (e.g. 24h, 7d, 30d) (default: `7d`)
`--json`	Output as JSON

squads brief

Read recent sessions, extract founder intentions, create GitHub issues

squads brief

Option	Description
`-n, --sessions <n>`	Number of recent sessions to read (default: `5`)
`--dry-run`	Show proposed issues without creating them
`--coo`	Write founder-focus.md for COO context

squads providers

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

squads providers

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

squads update

Check for and install updates

squads update

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

squads version

Show version information

squads version

squads commands

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

squads commands

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

​squads init

​squads add

​squads run

​squads list

​squads orchestrate

​squads env

​squads env show

​squads env prompt

​squads exec

​squads exec list

​squads exec show

​squads exec stats

​squads log

​squads dashboard

​squads status

​squads context

​squads cost

​squads budget

​squads usage

​squads health

​squads doctor

​squads history

​squads results

​squads goal

​squads goal set

​squads goal list

​squads goal complete

​squads goal progress

​squads kpi

​squads kpi list

​squads kpi show

​squads kpi record

​squads kpi trend

​squads kpi insights

​squads progress

​squads progress start

​squads progress complete

​squads feedback

​squads feedback add

​squads feedback show

​squads feedback stats

​squads autonomy

​squads autopilot

​squads stats

​squads memory

​squads memory query

​squads memory read

​squads memory write

​squads memory list

​squads memory sync

​squads memory search

​squads memory extract

​squads learn

​squads learnings

​squads learnings show

​squads learnings search

​squads sync

​squads trigger

​squads trigger list

​squads trigger sync

​squads trigger fire

​squads trigger enable

​squads trigger disable

​squads trigger status

​squads approval

​squads approval send

​squads approval list

​squads approval check

​squads approval cancel

​squads autonomous

​squads autonomous start

​squads autonomous stop

​squads autonomous status

​squads autonomous pause

​squads autonomous resume

​squads sessions

​squads sessions history

​squads sessions summary

​squads session

​squads session start