squads-cli in Action: Running Your First AI Workforce

TL;DR — squads-cli turns scattered AI agents into a coordinated workforce. Install in 30 seconds, define your squads, run them on a schedule. This is what that looks like in practice — real commands, real output, real cost.

What You’re Building

By the end of this tutorial, you’ll have a working AI squad that:

• Picks up context automatically (no prompt engineering per session)
• Remembers what happened in previous runs
• Produces real output: filed issues, updated docs, written content
• Reports its own cost and performance

This isn’t a demo with fabricated output. Every command below runs against a real squads-cli installation.

Prerequisites

• Node.js 18+
• Claude Code — squads-cli uses it as the agent executor
• Git — agents write to repos; history is the audit trail
• A GitHub repo for your “hq” (where squad definitions and memory live)

Step 1: Install

npm install -g squads-cli

That’s it. No Docker, no cloud signup, no config files to edit before you start.

Verify:

squads --version
# squads-cli/0.9.x

Step 2: Initialize Your Org

Point squads-cli at your hq repo:

git clone https://github.com/your-org/hq.git
cd hq
squads init

Output:

✓ Scanning .agents/squads/...
✓ Found 3 squads: marketing, engineering, operations
✓ Context layers loaded (company, priorities, goals)
✓ Memory connected (hq/.agents/memory/)
✓ Ready. Run: squads run <squad>

What just happened: squads-cli read your squad definitions, wired up the context system (company context, squad priorities, agent goals), and connected to memory storage. Every agent that runs will automatically receive this context — no manual copy-pasting required.

Step 3: Run a Squad

squads run marketing

Watch the output:

→ marketing-lead: loading context layers
  company.md ✓ | priorities.md ✓ | goals.md ✓ | state.md ✓

→ marketing-lead: checking open PRs...
  PR #18 feat(seo): keywords batch 2 — merged ✓
  PR #17 feat(content): product tutorial — awaiting CI

→ marketing-lead: reviewing goals (3 active)
  Goal 1: marketing deck v1 — in-progress (blocked: Drive auth)
  Goal 2: product demo script — not-started → starting now
  Goal 3: SEO baseline 33 articles — checking status...
  Goal 3: 44/44 articles verified → ACHIEVED

→ marketing-lead: writing product demo script → briefs/product-demo-v1.md
→ marketing-lead: filing issue #415 (social poster blocked)
→ marketing-lead: updating goals.md (Goal 3 achieved, Goal 2 in-progress)

✓ marketing-lead complete (4m 38s)
  Tasks: 4 completed
  Goals: 1 achieved, 2 in-progress
  Output: 2 files written, 1 issue filed, goals.md updated

The agent read its full context, picked up mid-run work (PR review), made progress on goals, escalated a blocker, and committed everything. No prompting required.

Step 4: Check What It Cost

squads obs cost --squad marketing --last-run

marketing-lead (last run: 4m 38s)
  Model:         claude-sonnet-4-6
  Input tokens:  43,812
  Output tokens:  9,204
  Total cost:    $0.19

Cumulative this week:
  Runs: 5
  Total cost: $0.87

Nineteen cents for a full marketing cycle — content written, PRs reviewed, goals updated, blockers escalated to the right people. Compare that to the hourly cost of the work being replaced.

Step 5: Check the Service Catalog

This is what separates squads-cli from every other AI CLI: a built-in IDP.

squads catalog check marketing

Service: marketing-squad
  Owner:        marketing-lead
  Status:       healthy
  Goals:        3 active (1 achieved today)
  Last run:     8 minutes ago
  Scorecard:    B+ (↑ from B-)
  Dependencies: website ✓  growth ✓  hq ✓
  Open issues:  2 (1 needs:human, 1 status:blocked)

Every squad is a service. It has an owner, a health status, a scorecard, and dependencies. When a squad is blocked, it shows up here. When quality drops, the scorecard catches it before it compounds.

No other AI CLI has this. Most AI agent frameworks give you agent execution. squads-cli gives you an org.

The Compounding Effect

Here’s what makes this different from running Claude Code manually:

Before squads-cli:

• Every session: copy context from docs, paste into prompt
• After each run: manually check what happened, update notes
• Multiple agents: run one at a time, sync manually, hope they don’t contradict each other
• No visibility: no idea what’s working, what agents cost, whether quality is improving

With squads-cli:

• Context loads automatically from structured layers (company → squad → agent)
• Memory persists — agents know what happened last run without being told
• Full org in one command: squads run --all
• Scorecards and cost tracking built in

Each cycle, agents update their own state, propose improvements to goals, and flag blockers. The org gets smarter with every run — not from retraining, but from accumulated, structured memory.

What to Build Next

Once your first squad runs clean:

1. Add more squads — finance, engineering, operations follow the same pattern
2. Set up triggers — squads trigger sync starts scheduled runs (cron-based)
3. Query memory — squads memory query "what did marketing ship last week" surfaces cross-run context
4. Read the IDP docs — scorecards and release pre-checks add accountability at scale

The getting-started docs are at agents-squads.com/docs/getting-started. The full command reference is at agents-squads.com/docs/commands.

squads-cli is free, open source, and runs entirely in your terminal.

npm install -g squads-cli