squads-cli

name	squads-cli
description	Squads CLI — operate your AI workforce through the loop; intent in, reviewed work out. TRIGGER when running squads, dispatching agents, triaging the inbox, reading/writing memory, recording feedback, or checking status/usage.
context	fork

Squads CLI

squads runs a business loop, not just commands: you (or an agent) express intent, squads execute it as bounded runs that end in reviewable artifacts, a human decides in the inbox, and the outcome feeds learning that shapes the next cycle.

        INTENT                     EXECUTE                     DECIDE
  ┌─────────────────┐      ┌──────────────────────┐      ┌──────────────┐
  │ goal set        │      │ run <squad> --task   │      │ inbox        │
  │ propose (CLI    │  →   │  bounded, PR-gated   │  →   │  approve /   │ → feedback → memory
  │  drafts work)   │      │ watch · kill         │      │  reject /    │    (LEARN — shapes
  └─────────────────┘      └──────────────────────┘      │  defer       │     the next cycle)
                                                          └──────────────┘
        always-on instruments: status · dash · usage · doctor

Every run is bounded (timeout, budget), contained (its own git worktree), and ends in an artifact (a PR, a proposal branch, an inbox card) — never loose changes to your working tree.

Who types what

Humans need five commands. Everything else is called by agents and automation.

Command	When you use it
squads status	"What's the state of my workforce?"
squads dash	Deeper view — per-squad detail, --ceo for the executive summary
squads inbox	Everything waiting on YOUR decision — approve / reject / defer <id>
squads usage	What today cost (--all-claude for machine-wide across projects)
squads login	Connect cloud features (optional — everything works local-first)

Agents use the working verbs — the rest of this file.

Core Concepts

Concept	Description
Squad	A team of agents in .agents/squads/{name}/ — defined by SQUAD.md
Agent	A markdown file ({agent}.md) inside a squad directory
Memory	Persistent state in .agents/memory/ — plain markdown, survives runs, portable to any provider (claude, gemini, opencode, …: memory is files, not vendor state)
Target	squad/agent notation (e.g., engineering/issue-solver)
Context cascade	Layered injection: SYSTEM → strategy → goals → agent → state
Inbox	The decision surface: run outcomes, proposals, and stranded work wait there; decisions land in an append-only reviewed.jsonl ledger with by: attribution

File Structure

.agents/
├── config/SYSTEM.md              # Immutable rules (all agents)
├── squads/{squad}/
│   ├── SQUAD.md                  # Squad identity, goals, KPIs
│   └── {agent}.md                # Agent definition
└── memory/
    ├── {squad}/
    │   ├── goals.md              # Measurable targets (primary squad context)
    │   ├── feedback.md           # Last cycle evaluation
    │   └── {agent}/state.md      # Agent's persistent state
    ├── company/strategy.md       # Company strategic context (L1)
    └── daily-briefing.md         # Cross-squad context

---

INTENT — tell the system what matters

squads goal set engineering "Zero CI failures on main branch"
squads goal list [squad]
squads goal complete engineering 1

# Or let the CLI draft work from repo intent (ambient):
squads propose                     # one bounded background run → proposal branch + inbox card

Business context for any run comes from the cascade — inspect it with:

squads context [--squad <name>] [--topic "pricing"] [--json]

EXECUTE — bounded runs that end in artifacts

# The workhorse: scoped task, one branch, one PR, stops at the PR gate
squads run engineering --task "Fix squads-cli#593 — spec in the issue" -t 40

# Single agent / squad conversation
squads run engineering/issue-solver
squads run research                        # lead briefs → workers → review → converge
squads run research --dry-run              # preview without executing

# Another provider (squads is provider-agnostic)
squads run research/analyst --provider=gemini

Bounds and containment:

Flag	Purpose
-t, --timeout <min>	Hard per-agent timeout
--cost-ceiling <usd>	Budget cap for the conversation
--max-turns <n>	Conversation turn limit
-b / -w	Detached / detached with log tail

While it runs — and if it goes wrong:

squads runs                        # live background runs
squads kill <target>               # stop one gracefully

If a run dies mid-work, uncommitted deliverables are auto-saved to a squads/run-* branch and flagged in the inbox as PARTIAL — work is never silently lost.

DECIDE — the inbox is the human gate

squads inbox                       # everything waiting on a human, one screen
squads inbox approve <id>          # PR items: arms CI-gated auto-merge
squads inbox reject <id> "reason"  # branches: archive-tag then delete; reason → feedback
squads inbox defer <id> --until <date>

Decisions are recorded in reviewed.jsonl with who decided (--by for bridges acting on someone's behalf). Autonomous actors must stamp themselves — never a human who didn't look.

LEARN — close the loop

# Rate what a run actually delivered (feeds provider/squad routing)
squads feedback add engineering 4 "PR merged clean, tests included"

# Persist knowledge for the next run
squads memory write engineering "Registry pattern: commands self-describe via commands --json"
squads memory read engineering
squads memory query "CI pipeline failures"     # search across all squads
squads sync --push                              # share memory across machines

# Executor quality-per-cost, from real outcomes
squads scoreboard

---

Instruments

squads status [squad] [-v] [--json]     # workforce state
squads dash [name] [--ceo]              # dashboards
squads usage [--all-claude]             # spend: project-scoped by default, machine-wide with the flag
squads doctor [-v]                      # tools, auth, project readiness — run this first when anything fails
squads providers                        # available LLM CLI lanes
squads pause <squad> / resume <squad>   # governance: a paused squad cannot be dispatched

Agent patterns (during execution)

# Orient: what am I working with, what do I know, what's the state?
squads env show ${SQUAD_NAME} --json
squads memory read ${SQUAD_NAME}
squads status --json

# Persist before you finish — memory is the only thing that survives you
squads memory write ${SQUAD_NAME} "Key finding from this run"

# Dispatch follow-up work as a bounded task, never as loose edits
squads run engineering --task "Fix the bug found in #461 — spec in issue" -b

Before creating issues or PRs, check what already exists: squads status <squad> -v + squads memory read <squad>.

Command surface

The verbs above are the canonical surface. Older command names (orchestrate, autopilot, autonomy, approval, learn, stats, cost, history, …) are deprecated aliases that print their replacement. Full generated reference: references/commands.md; authoritative for YOUR installed version: squads commands --json.

Troubleshooting

Problem	Fix
squads: command not found	npm install -g squads-cli
No squads found	Run squads init to create .agents/
No AI CLI installed	Init scaffolds in planning-only mode; install a provider then squads init --force --provider <id>
Agent not found	Check path: .agents/squads/{squad}/{agent}.md
Memory not persisting	Check .agents/memory/ exists, run squads sync
API quota exhausted	Wait for the window, switch --provider, or squads pause <squad>
Anything else	squads doctor -v