Overview

The squads CLI is your command interface for AI-native organizations. It bridges human intent and AI execution across 45+ commands organized by function.

Human Layer

Strategy, Goals, Oversight

AI Layer

Squads, Agents, Memory

Output

Decisions, Artifacts, Reports

Installation

npm install -g squads-cli

Requirements: Node.js 18+, Git, Claude Code (optional)

Quick Reference

Category	Commands
Getting Started	`init`, `setup`, `login`, `whoami`, `update`
Status & Monitoring	`status`, `dash`, `health`, `workers`, `sessions`, `live`, `top`, `watch`
Running Agents	`run`, `orchestrate`, `tonight`
Goals & Memory	`goal`, `memory`, `kpi`, `learn`, `learnings`, `feedback`
Issues & Progress	`issues`, `solve-issues`, `open-issues`, `progress`, `results`, `history`
Cost & Autonomy	`cost`, `budget`, `autonomy`
Infrastructure	`stack`, `trigger`, `cron`, `autonomous`
Integrations	`slack`, `skill`, `approval`, `permissions`
Context	`context`, `env`, `providers`, `list`

Getting Started

squads init

Initialize a new squads project with guided setup.

# Interactive setup (recommended)
squads init

# Quick init - files only, no guided setup
squads init --quick

# Non-interactive with defaults
squads init --yes

# Specify LLM provider
squads init --provider gemini

Options:

Flag	Description
`-t, --template <template>`	Project template (default: “default”)
`-p, --provider <provider>`	LLM provider: claude, gemini, openai, ollama, none
`--skip-infra`	Skip infrastructure setup prompt
`-y, --yes`	Accept all defaults (non-interactive)
`-q, --quick`	Quick init - create files only

Creates:

.agents/
├── squads/
│   └── engineering/
│       └── SQUAD.md
└── memory/
.claude/
└── settings.json
CLAUDE.md

squads setup

Guided onboarding for infrastructure, auth, and first squad.

# Full guided setup
squads setup

# Resume from last checkpoint
squads setup --resume

# Skip infrastructure
squads setup --skip-infra

Options:

Flag	Description
`-p, --provider <provider>`	LLM provider
`--skip-infra`	Skip infrastructure setup
`-y, --yes`	Accept all defaults
`-r, --resume`	Resume from last checkpoint

squads login

Opens browser for OAuth authentication.

squads whoami

Show current logged in user and subscription status.

squads whoami

squads update

Check for and install CLI updates.

# Check and prompt for update
squads update

# Auto-confirm update
squads update --yes

# Check only, don't install
squads update --check

Status & Monitoring

squads status

Show squad status and state overview.

# All squads overview
squads status

# Single squad details
squads status engineering

# Verbose with agent list
squads status engineering -v

Output shows: Squad name, agent count, memory entries, last activity.

squads dash

Full dashboard with goals, metrics, and activity.

# Overview dashboard
squads dash

# Executive summary with priorities
squads dash --ceo

# Include GitHub PR/issue stats (slower)
squads dash --full

# List available dashboards
squads dash --list

# Specific dashboard
squads dash token-economics

Options:

Flag	Description
`-v, --verbose`	Show additional details
`-c, --ceo`	Executive summary with priorities and blockers
`-f, --full`	Include GitHub PR/issue stats (~30s)
`-l, --list`	List available dashboards
`--view <view>`	Render specific view from dashboard

squads health

Quick health check for all infrastructure services.

squads health

# Include optional services
squads health --verbose

Checks: Postgres, Redis, Claude CLI, GitHub CLI, Slack connection.

squads workers

Show active workers: Claude sessions, agent workers, background tasks.

# List active workers
squads workers

# Show details
squads workers --verbose

# Kill a specific process
squads workers --kill <pid>

# Clean up zombie sessions (>24h old)
squads workers --cleanup

# Kill ALL agent tmux sessions
squads workers --all

Options:

Flag	Description
`-v, --verbose`	Show more details
`-k, --kill <pid>`	Kill process by PID or tmux session name
`-c, --cleanup`	Kill zombie sessions (>24h old)
`-a, --all`	Kill ALL agent tmux sessions

squads sessions

Show active Claude Code sessions across squads.

# List active sessions
squads sessions

# With details
squads sessions --verbose

# Output as JSON
squads sessions --json

# Session history and statistics
squads sessions history

# Pretty session summary
squads sessions summary

squads live

Live TUI dashboard with real-time metrics (like htop).

# Full dashboard
squads live

# Minimal view
squads live --minimal

# Focus on specific panel
squads live --focus agents
squads live --focus cost
squads live --focus activity
squads live --focus memory

squads top

Live process table (like Unix top) - numbers update in place.

squads top

Shows real-time CPU, memory, and token usage per agent.

squads watch

Live refresh any squads command (like Unix watch).

# Watch status every 2 seconds
squads watch status

# Custom interval
squads watch -n 5 "dash --ceo"

# Don't clear screen
squads watch --no-clear workers

Options:

Flag	Description
`-n, --interval <seconds>`	Refresh interval (default: 2)
`--no-clear`	Don’t clear screen between refreshes

Running Agents

squads run

Execute a squad or specific agent.

# Run entire squad (shows agent list)
squads run engineering

# Run specific agent (slash notation)
squads run engineering/code-review

# Run specific agent (flag notation)
squads run engineering -a code-review

# Preview without executing
squads run engineering --dry-run

# Execute via Claude CLI
squads run engineering --execute

# Run all agents in parallel (tmux)
squads run engineering --parallel

# Single orchestrator with Task tool
squads run engineering --lead

# Run in foreground (blocks terminal)
squads run engineering --foreground

# Use different provider
squads run research --provider=google

# Specify model
squads run engineering --model opus

Options:

Flag	Description
`-d, --dry-run`	Preview what would run
`-e, --execute`	Execute via Claude CLI
`-a, --agent <agent>`	Run specific agent within squad
`-t, --timeout <minutes>`	Execution timeout (default: 30)
`-p, --parallel`	Run all agents in parallel (N tmux sessions)
`-l, --lead`	Lead mode: single orchestrator using Task tool
`-f, --foreground`	Run in foreground (no tmux)
`--use-api`	Use API credits instead of subscription
`--effort <level>`	Effort level: high, medium, low
`--skills <skills...>`	Skills to load
`--provider <provider>`	LLM provider: anthropic, google, openai, etc.
`--model <model>`	Model: opus, sonnet, haiku (default: sonnet)
`--trigger <type>`	Trigger source: manual, scheduled, event, smart

squads orchestrate

Run squad with lead agent orchestration - a single lead spawns workers.

# Run with orchestration
squads orchestrate engineering

# Interactive mode
squads orchestrate engineering --foreground

# With timeout
squads orchestrate engineering --timeout 120

# Verbose with event watching
squads orchestrate engineering --verbose

Options:

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

squads tonight

Run agents autonomously overnight with safety limits.

# Start tonight mode
squads tonight run engineering research

# Check status
squads tonight status

# Stop all and generate report
squads tonight stop

# View latest report
squads tonight report

Subcommands:

Command	Description
`run <targets...>`	Start tonight mode with specified squads/agents
`status`	Check tonight mode status
`stop`	Stop all tonight agents and generate report
`report`	Show latest tonight report

Goals & Memory

squads goal

Set and track goals for squads.

# List all goals
squads goal list

# List goals for specific squad
squads goal list engineering

# Set a goal
squads goal set engineering "Ship authentication feature"

# Mark goal as completed
squads goal complete engineering 1

# Update goal progress
squads goal progress engineering 1 75

Subcommands:

Command	Description
`list [squad]`	List goals for squad(s)
`set <squad> <description>`	Set a goal for a squad
`complete <squad> <index>`	Mark a goal as completed
`progress <squad> <index> <progress>`	Update goal progress (0-100)

squads memory

Query and manage persistent agent memory.

# Search across all memory
squads memory query "competitor analysis"

# View squad memory
squads memory show research

# Add to squad memory
squads memory update research "Found: MCP adoption at 15%"

# List all memory entries
squads memory list

# Sync memory from git
squads memory sync

# Sync and push to git
squads memory sync --push

# Search conversations in postgres
squads memory search "authentication"

# Extract memories from conversations
squads memory extract

Subcommands:

Command	Description
`query <query>`	Search across all squad memory
`show <squad>`	Show memory for a squad
`update <squad> <content>`	Add to squad memory
`list`	List all memory entries
`sync`	Sync memory from git
`search <query>`	Search conversations in postgres
`extract`	Extract memories from recent conversations

squads kpi

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

# List all KPIs
squads kpi list

# Show KPI status for squad
squads kpi show engineering

# Record a KPI value
squads kpi record engineering leads_generated 15

# Show KPI trend over time
squads kpi trend engineering leads_generated

# Generate insights from KPI data
squads kpi insights
squads kpi insights engineering

Subcommands:

Command	Description
`list`	List all KPIs across squads
`show <squad>`	Show KPI status for a squad
`record <squad> <kpi> <value>`	Record a KPI value
`trend <squad> <kpi>`	Show KPI trend over time
`insights [squad]`	Generate insights from KPI data

squads learn

Capture learnings that persist across sessions.

# Capture a learning
squads learn "PostgreSQL pool exhaustion was caused by unclosed transactions"

# With squad and category
squads learn "Always check memory before researching" --squad engineering --category pattern

# With tags
squads learn "Use pnpm for 40% faster CI builds" --tags "ci,performance"

Options:

Flag	Description
`-s, --squad`	Associate with squad (default: general)
`-c, --category`	Category: success, failure, pattern, tip
`-t, --tags`	Comma-separated tags
`--context`	Additional context

squads learnings

View and search learnings.

# View squad learnings
squads learnings show engineering

# Limit results
squads learnings show engineering -n 5

# Filter by category
squads learnings show engineering --category pattern

# Search learnings
squads learnings search "authentication"

squads feedback

Record and view execution feedback for continuous improvement.

# Record feedback after execution
squads feedback add research

# View feedback history
squads feedback show research

# View aggregate statistics
squads feedback stats

Issues & Progress

squads issues

Show GitHub issues across repos.

# List issues
squads issues

# Specific organization
squads issues --org agents-squads

# Specific repos
squads issues --repos hq,agents-squads-web

squads solve-issues

Solve ready-to-fix issues by creating PRs.

# Show what would be solved
squads solve-issues --dry-run

# Solve specific issue
squads solve-issues --repo hq --issue 42

# Execute with Claude CLI
squads solve-issues --repo hq --issue 42 --execute

Options:

Flag	Description
`-r, --repo <repo>`	Target repo (hq, agents-squads-web)
`-i, --issue <number>`	Specific issue number
`-d, --dry-run`	Show what would be solved
`-e, --execute`	Execute with Claude CLI

squads open-issues

Run evaluators/critics to find and create issues.

# Show what would run
squads open-issues --dry-run

# Run for specific squad
squads open-issues --squad website

# Run specific evaluator
squads open-issues --squad engineering --agent security-critic

# Execute
squads open-issues --squad website --execute

squads progress

Track active and completed agent tasks.

# List progress
squads progress

# Verbose
squads progress --verbose

# Start a new task
squads progress start engineering "Implementing auth flow"

# Complete a task
squads progress complete task-123

squads results

Show squad results: git activity + KPI goals vs actuals.

# Last 7 days (default)
squads results

# Specific squad
squads results engineering

# Last 30 days
squads results --days 30

# Verbose with detailed KPIs
squads results engineering --verbose

squads history

Show recent agent execution history.

# Last 7 days
squads history

# Last 30 days
squads history --days 30

# Filter by squad
squads history --squad engineering

# With cost and token details
squads history --verbose

# Output as JSON
squads history --json

squads exec

View execution history and statistics.

# List recent executions
squads exec list

# Show execution details
squads exec show exec-123

# Show execution statistics
squads exec stats

Cost & Autonomy

squads cost

Show cost summary (today, week, by squad).

# Cost summary
squads cost

# Filter to specific squad
squads cost --squad engineering

# Output as JSON
squads cost --json

squads budget

Check budget status for a squad.

# Check budget
squads budget engineering

# Output as JSON
squads budget engineering --json

squads autonomy

Show autonomy score and confidence metrics.

# Today's autonomy
squads autonomy

# Filter by squad
squads autonomy --squad engineering

# Different time periods
squads autonomy --period week
squads autonomy --period month

# Output as JSON
squads autonomy --json

Metrics: Success rate, human intervention rate, confidence scores.

Infrastructure

squads stack

Manage local Docker stack (postgres, redis, langfuse, bridge).

# Auto-detect and configure containers
squads stack init

# Show container health
squads stack status

# Print env vars for shell
squads stack env

# Start containers
squads stack up

# Stop containers
squads stack down

# Comprehensive health check
squads stack health

# View service logs
squads stack logs postgres
squads stack logs redis

Subcommands:

Command	Description
`init`	Auto-detect Docker containers and configure
`status`	Show container health and connection status
`env`	Print environment variables for shell export
`up`	Start Docker containers
`down`	Stop Docker containers
`health`	Comprehensive health check with diagnostics
`logs <service>`	Show logs for a service

squads trigger

Manage smart triggers for automated agent execution.

# List triggers
squads trigger list

# List for specific squad
squads trigger list engineering

# Sync SQUAD.md triggers to scheduler
squads trigger sync

# Manually fire a trigger
squads trigger fire daily-standup

# Enable/disable triggers
squads trigger enable daily-standup
squads trigger disable daily-standup

# Show scheduler status
squads trigger status

squads cron

Manage local cron schedules for agents (macOS only).

# Sync schedules from .md files to launchd
squads cron sync

# List scheduled agents
squads cron list
squads cron list engineering

# Show cron status and next runs
squads cron status

# View execution logs
squads cron logs
squads cron logs engineering/reporter

# Enable/disable agent schedule
squads cron enable engineering/reporter
squads cron disable engineering/reporter

squads autonomous

Manage autonomous agent execution (scheduler daemon).

# Start scheduler daemon
squads autonomous start

# Stop scheduler daemon
squads autonomous stop

# Show scheduler status
squads autonomous status

# Sync routines from SQUAD.md files
squads autonomous sync

Also available as squads auto.

Integrations

squads slack

Manage Slack integration.

# Sync squad channels with Slack
squads slack sync

# List Slack channels
squads slack channels

# Test Slack connection
squads slack test

squads skill

Manage Agent Skills (Anthropic API).

# List uploaded skills
squads skill list

# Upload a skill directory
squads skill upload ./my-skill

# Show skill details
squads skill show skill-123

# Delete a skill
squads skill delete skill-123

# Convert agent.md to SKILL.md format
squads skill convert engineering/code-review

squads approval

Manage approval requests for agent actions.

# Send approval request
squads approval send deploy

# List approvals
squads approval list

# Check approval status
squads approval check approval-123

# Cancel pending approval
squads approval cancel approval-123

squads permissions

Manage and validate squad permissions.

# Show permission context for squad
squads permissions show engineering

# Validate permissions before execution
squads permissions check engineering

Also available as squads perms.

Context & Environment

squads context

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

# Full context
squads context

# Focus on specific squad
squads context --squad engineering

# Search memory for relevant context
squads context --topic "authentication"

# Output for agent consumption (JSON)
squads context --agent
squads context --json

# Verbose
squads context --verbose

Also available as squads feed.

squads env

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

# Show environment for squad
squads env show engineering

# List environment for all squads
squads env list

# Activate execution context (generates scoped MCP config)
squads env activate engineering

squads providers

Show available LLM CLI providers and installation status.

squads providers

# Output as JSON
squads providers --json

Output:

Provider     CLI       Status
────────────────────────────────────────
Anthropic    claude    ✓ ready
Google       gemini    ✓ ready
OpenAI       codex     ✗ not installed

squads list

List all agents and squads in the project.

squads list

Environment Variables

Variable	Description
`SQUADS_PROJECT_PATH`	Override default project path
`SQUADS_CONFIG_PATH`	Custom config file location
`SQUADS_PLAN_TYPE`	Plan type: `max` or `usage`
`DATABASE_URL`	PostgreSQL connection string
`REDIS_URL`	Redis connection string
`SLACK_BOT_TOKEN`	Slack bot token for notifications

Configuration

The CLI reads configuration from multiple sources:

SQUAD.md frontmatter - Per-squad settings
.claude/settings.json - Claude Code hooks
Environment variables - Infrastructure connections

Example .claude/settings.json for auto-injecting status:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "squads status",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Documentation Index

​Overview

Human Layer

AI Layer

Output

​Installation

​Quick Reference

​Getting Started

​squads init

​squads setup

​squads login

​squads whoami

​squads update

​Status & Monitoring

​squads status

​squads dash

​squads health

​squads workers

​squads sessions

​squads live

​squads top

​squads watch

​Running Agents

​squads run

​squads orchestrate

​squads tonight

​Goals & Memory

​squads goal

​squads memory

​squads kpi

​squads learn

​squads learnings

​squads feedback

​Issues & Progress

​squads issues

​squads solve-issues

​squads open-issues

​squads progress

​squads results

​squads history

​squads exec

​Cost & Autonomy

​squads cost

​squads budget

​squads autonomy

​Infrastructure

​squads stack

​squads trigger

​squads cron

​squads autonomous

​Integrations

​squads slack

​squads skill

​squads approval

​squads permissions

​Context & Environment

​squads context

​squads env

​squads providers

​squads list

​Environment Variables

​Configuration

Overview

Installation

Quick Reference

Getting Started

squads init

squads setup

squads login

squads whoami

squads update

Status & Monitoring

squads status

squads dash

squads health

squads workers

squads sessions

squads live

squads top

squads watch

Running Agents

squads run

squads orchestrate

squads tonight

Goals & Memory

squads goal

squads memory

squads kpi

squads learn

squads learnings

squads feedback

Issues & Progress

squads issues

squads solve-issues

squads open-issues

squads progress

squads results

squads history

squads exec

Cost & Autonomy

squads cost

squads budget

squads autonomy

Infrastructure

squads stack

squads trigger

squads cron

squads autonomous

Integrations

squads slack

squads skill

squads approval

squads permissions

Context & Environment

squads context

squads env

squads providers

squads list

Environment Variables

Configuration