Squad CLI Command Reference

The Squad CLI is installed globally via npm and provides a full suite of commands for team lifecycle management, automated issue triage, state management, and observability. Every Squad workflow — from scaffolding your first team to running overnight automation with Ralph — flows through this interface.

Installation

Squad requires Node.js ≥ 22.5.0. The node:sqlite module (used by the Copilot SDK for session storage) was introduced in Node 22.5.0. Squad will exit immediately with a clear error message if you run it on an older version.

npm install -g @bradygaster/squad-cli

After installation, run squad help to verify the CLI is working and see the full command list.

Command Summary

Command	What it does
`squad init`	Scaffold Squad in the current directory (idempotent)
`squad upgrade`	Update Squad-owned files to the latest version
`squad status`	Show which squad is active and why
`squad triage` / `watch`	Watch mode — poll for issues and auto-triage (Ralph)
`squad loop`	Prompt-driven continuous work loop (no issues required)
`squad copilot`	Add or remove the Copilot coding agent
`squad doctor`	Check setup and diagnose issues
`squad link <path>`	Connect to a remote team
`squad externalize`	Move `.squad/` state outside the working tree
`squad internalize`	Move externalized state back into `.squad/`
`squad export`	Export squad to a portable JSON snapshot
`squad import <file>`	Import squad from an export file
`squad plugin marketplace`	Manage plugin marketplaces
`squad upstream`	Manage upstream Squad sources
`squad nap`	Context hygiene — compress, prune, archive
`squad aspire`	Open Aspire dashboard for observability
`squad scrub-emails`	Remove email addresses from Squad state files
`squad build`	Generate `.squad/` markdown from `squad.config.ts`

Commands

squad init — Scaffold Squad in your project

Initialize Squad in the current directory. This command is idempotent — it is safe to run multiple times without overwriting your existing team state. The alias hire runs the same command.

squad init

Flags

Flag	Description
`--preset <name>`	Apply a preset after init (e.g. `--preset default` for a fully-configured squad)
`--global`	Initialize in your personal squad directory (`~/.config/squad/`) instead of the current project
`--mode remote <path>`	Dual-root mode — write a remote config pointing to an external team root
`--no-workflows`	Skip GitHub Actions workflow setup
`--sdk`	Use SDK builder syntax instead of markdown
`--state-backend <type>`	Choose a state backend: `local`, `orphan`, or `two-layer`

Examples

# Walk through interactive setup (recommended first time)
squad init

# Instant team with default agents, routing rules, and charters
squad init --preset default

# Personal squad that persists across all projects
squad init --global

# Dual-root mode — share squad state stored in another repo
squad init --mode remote ../my-team-repo

Use --preset default to get a fully wired squad in under a second. The bare squad init walks you through setup step by step, which is ideal when you want to customize your team deliberately.

What gets createdAfter squad init you will find:

.squad/
├── team.md
├── routing.md
├── decisions/inbox/
├── ceremonies.md
├── casting/
├── agents/
├── skills/
├── identity/
│   ├── now.md
│   └── wisdom.md
└── log/
.github/agents/squad.agent.md

squad upgrade — Update Squad-owned files

Update Squad-owned files (squad.agent.md, templates, GitHub workflows) to the latest versions. Your team state in .squad/ is never touched — agents, decisions, and history are always preserved.

squad upgrade

Flags

Flag	Description
`--self`	Update the Squad CLI package itself (runs `npm install -g`)
`--force`	Re-apply updates even when the installed version already matches the latest
`--global`	Upgrade the personal squad at `~/.config/squad/`
`--migrate-directory`	Rename `.ai-team/` to `.squad/` (for teams migrating from the older directory name)
`--insider`	Use the dev-channel prerelease build (only valid with `--self`)
`--state-backend <type>`	Migrate to a new state backend as part of the upgrade

Examples

# Update Squad-owned files in the current project
squad upgrade

# Update the CLI binary itself
squad upgrade --self

# Update to the insider (prerelease) build
squad upgrade --self --insider

# Migrate from .ai-team/ to .squad/ and upgrade files
squad upgrade --migrate-directory

squad status — Show active squad

Show which squad is currently active and explain why Squad resolved it that way. Useful for diagnosing resolution issues in monorepos or projects with both a repo squad and a personal squad.

squad status

Output includes:

Whether the active squad is a repo squad (.squad/ found in the repository tree), a personal squad (global path), or none
The resolved path for the active squad
The resolution reason
Both the repo resolution path and the global path for comparison

No flags are required. The command reads your current directory and ~/.config/squad/ to determine context.

squad triage / watch — Watch mode (Ralph)

Watch mode is Squad’s automated triage and execution loop, powered by Ralph. Ralph polls for GitHub Issues on a configurable interval, triages them to agents, and — with --execute — dispatches Copilot sessions to work on actionable issues automatically.The commands triage and watch are aliases for the same watch runner. loop is a separate prompt-driven continuous work loop that does not require GitHub Issues — see the loop entry below.

# Triage mode only (no execution)
squad triage

# Auto-execute against actionable issues
squad watch --execute --interval 5

Core flags

Flag	Description
`--execute`	Spawn Copilot agents to work on actionable issues
`--interval <minutes>`	Poll every N minutes (default: 10)
`--agent-cmd`	Custom agent command (default: `gh copilot`)
`--copilot-flags`	Extra flags passed to the agent runner
`--auth-user`	GitHub account to use for agent auth
`--log-file <path>`	Mirror output to a file for later review
`--verbose`	Show extra diagnostic output
`--health`	Show status of a running watch process and exit
`--max-concurrent <n>`	Maximum number of issues being worked in parallel (default: 1)
`--timeout <minutes>`	Maximum minutes to spend on a single issue (default: 30)
`--dispatch-mode`	Execution strategy: `task`, `fleet`, or `hybrid`
`--state-backend`	Persistence strategy: `local`, `orphan`, or `two-layer`
`--overnight-start HH:MM`	Pause watch during off-hours
`--overnight-end HH:MM`	Resume watch at this time
`--notify-level`	Output verbosity: `all`, `important`, or `none`

See Watch Mode for the complete guide including error recovery, state backends, and overnight scheduling.

squad copilot — Add/remove the Copilot agent

Add or remove the Copilot coding agent (@copilot) from your squad’s team configuration.

squad copilot

Flags

Flag	Description
`--off`	Remove the Copilot agent from the team
`--auto-assign`	Enable auto-assignment of issues to the Copilot agent

Examples

# Add the Copilot agent
squad copilot

# Remove the Copilot agent
squad copilot --off

# Add with auto-assignment enabled
squad copilot --auto-assign

squad doctor / heartbeat — Diagnose setup

Validate your Squad setup and diagnose common configuration problems. The alias heartbeat runs the same command.

squad doctor

squad doctor checks:

That .squad/ is present and well-formed
That required files (team.md, routing.md, etc.) exist
That GitHub authentication is accessible
That the CLI version is compatible

Run this first when anything isn’t working as expected.

squad link — Connect to a remote team

Link the current project to a remote team root. This is useful when you want multiple projects to share the same squad state stored in a separate repository.

squad link <team-repo-path>

Example

squad link ../shared-team-repo

This writes a .squad/config.json pointing to the external team root. The shorthand squad init-remote <path> is equivalent.

squad externalize — Move state outside the working tree

Move .squad/ state outside the working tree so it survives branch switches. This is useful on projects where you frequently switch branches and don’t want to lose squad state.

squad externalize

Flags

Flag	Description
`--key <name>`	Custom project key for the externalized state directory

Examples

# Externalize with an auto-generated key
squad externalize

# Externalize with a specific key
squad externalize --key my-project

Use squad internalize to move the state back into .squad/ in the working tree.

squad internalize — Move state back into the tree

Move externalized squad state back into .squad/ in the working tree. This is the reverse of squad externalize.

squad internalize

No flags required.

squad export — Export to a JSON snapshot

Export your squad to a portable JSON snapshot. Useful for backups, sharing, and moving squads between repositories.

squad export

By default, the snapshot is written to squad-export.json. Use --out <path> to specify a custom output path.

# Export to default file
squad export

# Export to a named file
squad export --out ./backups/squad-2025.json

squad import — Import from a snapshot

Import a squad from a previously exported JSON snapshot.

squad import <file>

Flags

Flag	Description
`--force`	Overwrite existing squad state

Examples

# Import from file
squad import ./squad-export.json

# Import and overwrite existing state
squad import ./squad-export.json --force

squad plugin marketplace — Manage plugin marketplaces

Manage plugin marketplaces to extend Squad with additional agent skills and capabilities.

squad plugin marketplace <add|remove|list|browse>

Subcommands

Subcommand	Description
`add <url>`	Register a new marketplace
`remove <name>`	Remove a registered marketplace
`list`	List all registered marketplaces
`browse`	Browse available plugins interactively

See Plugins and Marketplace for the full guide.

squad upstream — Manage upstream sources

Manage upstream Squad sources — external repos that contribute templates, skills, or agent definitions to your squad.

squad upstream <add|remove|list|sync>

Subcommands

Subcommand	Description
`add <source>`	Add an upstream source (supports `--name` and `--ref` flags)
`remove <name>`	Remove an upstream source
`list`	List registered upstream sources
`sync [name]`	Sync from upstream(s)

Example

squad upstream add https://github.com/org/squad-base --name base --ref main
squad upstream sync

squad nap — Context hygiene

Run context hygiene operations on your squad state: compress bloated context files, prune stale entries, and archive old session logs. Helps keep agent context lean and focused over the lifetime of a long-running project.

squad nap

Flags

Flag	Description
`--deep`	Thorough compression and archival (more aggressive than default)
`--dry-run`	Preview all changes without writing anything

Examples

# Standard hygiene pass
squad nap

# Preview what would be cleaned up
squad nap --dry-run

# Aggressive compression and archival
squad nap --deep

squad aspire — Observability dashboard

Launch the .NET Aspire dashboard for real-time observability of your Squad runtime — traces, logs, metrics, and agent session telemetry.

squad aspire

Flags

Flag	Description
`--docker`	Force the Docker-based dashboard (instead of standalone)
`--port <n>`	Custom port for the dashboard (default varies by backend)

See Observability for setup instructions and dashboard tour.

squad scrub-emails — Remove email addresses

Remove email addresses from Squad state files. Useful before committing .squad/ to a public repository or sharing an export snapshot.

squad scrub-emails [directory]

The default target directory is .squad/. Pass a path to target a different directory.Examples

# Scrub the default .squad/ directory
squad scrub-emails

# Scrub a custom directory
squad scrub-emails ./exports

squad build — Generate markdown from squad.config.ts

Compile a squad.config.ts file (SDK-first mode) into .squad/ markdown files. This is the entry point for teams who prefer to define their squad in TypeScript.

squad build

Flags

Flag	Description
`--check`	Validate the config without writing any files
`--dry-run`	Preview generated output without writing
`--watch`	Rebuild automatically when `squad.config.ts` changes

Examples

# Build once
squad build

# Validate without writing
squad build --check

# Rebuild on every save
squad build --watch

See Configuration for the full squad.config.ts reference.

Interactive Shell (Deprecated)

The interactive shell (squad with no arguments) is deprecated. For the best Squad experience, use the GitHub Copilot CLI instead:

copilot --agent squad

Running squad without any arguments still launches the interactive shell for backward compatibility. Inside the shell you get a squad > prompt and can talk to your team in natural language.

Shell commands

All shell commands start with /:

Command	What it does
`/status`	Check your team and what’s happening
`/history`	See recent messages
`/agents`	List all team members
`/sessions`	List saved sessions
`/resume <id>`	Restore a past session
`/version`	Show version
`/clear`	Clear the screen
`/help`	Show all commands
`/quit`	Exit the shell (or Ctrl+C)

You can also address agents by name using @AgentName or natural language — the coordinator routes your message to the right specialist automatically.

Something not working? Run squad doctor first. It checks your setup, validates the .squad/ directory, and surfaces the most common configuration problems with clear remediation steps.

Get Started

CLI Reference

Guides

SDK

Samples & Examples

Squad CLI Command Reference

Installation

Command Summary

Commands

Interactive Shell (Deprecated)

Shell commands

Build docs developers (and LLMs) love

Get Started

CLI Reference

Guides

SDK

Samples & Examples

Documentation Index

​Installation

​Command Summary

​Commands

​Interactive Shell (Deprecated)

​Shell commands

Build docs developers (and LLMs) love

Installation

Command Summary

Commands

Interactive Shell (Deprecated)

Shell commands