CLI Reference

⚠️ Experimental — Squad is alpha software. APIs, commands, and behavior may change between releases.

Everything you need to run Squad from the command line — commands, shell interactions, configuration files, and environment variables.

Installation

# Global install (recommended)
npm install -g @bradygaster/squad-cli

# One-off with npx
npx @bradygaster/squad-cli init

# Latest from GitHub (bleeding edge)
squad init

CLI Commands (16 commands)

Remote Init Mode

Use --mode remote to link your project to a shared team root:

squad init --mode remote ../team-repo

In dual-root mode, project-specific state lives in your local .squad/ while team identity (casting, charters, shared decisions) lives in the remote location. This is useful for monorepos or organizations with a shared team definition.

squad start

Start Copilot with optional remote access via phone. Spawns Copilot in a PTY and mirrors to your phone via WebSocket + devtunnel.

Flags:

• --tunnel — Create a devtunnel for remote access (shows QR code for phone scanning). Requires devtunnel CLI installed and authenticated (devtunnel user login).
• --port <N> — Specific WebSocket port (default: random). Example: --port 3456
• --command <cmd> — Run a custom command instead of copilot. Example: --command powershell
• All copilot flags pass through. Example: squad start --tunnel --yolo or squad start --tunnel --model gpt-4

Examples:

# Basic local PTY (no phone access)
squad start

# With phone access + devtunnel
squad start --tunnel
# Output: QR Code, URL, Session ID

# Custom port, local only
squad start --port 3456

# Custom command with tunnel
squad start --tunnel --command powershell

# Copilot flags pass through
squad start --tunnel --yolo
squad start --tunnel --model gpt-4 --no-config

For details on architecture, security, mobile keyboard, and troubleshooting, see Remote Control Guide.

Interactive Shell

Enter the shell with squad (no arguments). You’ll see:

squad >

Shell Commands

All shell commands start with /.

Addressing Agents

squad > @Keaton, analyze the architecture
squad > Keaton, set up the database schema
squad > Build a blog post about our casting system

Agent name matching is case-insensitive — @keaton, @Keaton, and @KEATON all route to the same agent. Name an agent to route directly. Omit the name and the coordinator routes to the best fit.

Keyboard Shortcuts

Configuration Files

.squad/ Directory Structure

.squad/
├── team.md              # Roster — agent names, roles, human members
├── routing.md           # Work routing rules
├── decisions.md         # Architectural decisions log
├── directives.md        # Permanent team rules and conventions
├── casting-state.json   # Agent names, universe theme
├── model-config.json    # Per-agent model overrides
├── ceremonies.md        # Team ceremonies and rituals
├── skills/              # Reusable knowledge (markdown files)
│   ├── auth-rate-limiting.md
│   └── ...
├── agents/
│   ├── neo/
│   │   ├── charter.md   # Role definition, expertise, tools
│   │   └── history.md   # Accumulated knowledge
│   └── ...
└── history-archive/     # Archived old session logs

team.md

Defines the roster. Squad generates this during init, but you can edit it:

## Team

🏗️  Neo      — Lead          Scope, decisions, code review
⚛️  Trinity  — Frontend Dev  React, TypeScript, UI
🔧  Morpheus — Backend Dev   Node.js, Express, Prisma
🧪  Tank     — Tester        Jest, integration tests
📋  Scribe   — (silent)      Memory, decisions, session logs

## Human Team Members

- **Sarah** — Senior Backend Engineer
- **Jamal** — Frontend Lead

routing.md

Controls which agent gets which work:

# Routing Rules

**Frontend changes** → Trinity
**Backend API work** → Morpheus
**Database migrations** → Morpheus
**Test writing** → Tank
**Architecture decisions** → Neo
**Backend architecture decisions** → Sarah (human)

decisions.md

Append-only log of architectural decisions. Agents read this before every task:

### 2025-07-15: Use Zod for API validation
**By:** Morpheus
**What:** All API input validation uses Zod schemas
**Why:** Type-safe, composable, generates TypeScript types

directives.md

Permanent rules agents always follow:

- Always use TypeScript strict mode
- No any/unknown casts
- All database queries through Prisma, no raw SQL

Resolution Order

When Squad starts, it looks for .squad/ in this order:

1. Current directory (./.squad/)
2. Parent directories (walk up to project root)
3. Personal squad directory (platform-specific: ~/.config/squad/ on Linux, ~/Library/Application Support/squad/ on macOS, %APPDATA%\squad\ on Windows)
4. Global CLI default (fallback only)

First match wins.

Environment Variables

Troubleshooting with squad doctor

When something isn’t working, run:

squad doctor

This performs a comprehensive diagnostic check of your Squad setup, validating:

• .squad/ directory structure
• Required configuration files (team.md, routing.md, etc.)
• Agent definitions and capabilities
• File permissions and integrity
• Integration with GitHub and Copilot

Usage Examples

# Run diagnostics on the current project
squad doctor

# Quick check after upgrading Squad
squad upgrade && squad doctor

# Verify setup after cloning a repo with a squad
git clone my-project && cd my-project && squad doctor

Example Output

✓ .squad/ directory exists
✓ team.md is readable and valid
✓ 4 agents registered
⚠ skills/ directory is empty — consider adding documentation
✓ .gitattributes rules applied

The doctor always exits cleanly (no error code) because it’s a diagnostic tool, not a gate. Use it to troubleshoot setup issues, validate team state, or run before opening an issue on GitHub.

Version Management

squad --version                              # Check version
npm install -g @bradygaster/squad-cli@latest # Update
npm install -g @bradygaster/squad-cli@1.2.3  # Pin version
npm install -g @bradygaster/squad-cli@insider # Insider builds

See Also

• SDK Reference — Programmatic API
• Recipes & Advanced Scenarios — Prompt-driven cookbook
• Adding Squad to an Existing Repo — Getting started walkthrough