squads-cli in Action: Running Your First Squad

TL;DR — squads-cli organizes AI agents into squads defined in markdown. Install it, define your squads, and run them on demand or 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

The last run cost $0.19 (43,812 input and 9,204 output tokens); the week’s five runs cost $0.87 in total. That bought a demo script, a PR status check, updated goals, and a filed blocker. It is model cost only; it doesn’t include the time you spend reviewing the output.

Step 5: Check the Service Catalog

squads-cli includes a built-in service catalog (an 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. The scorecard tracks quality across runs, so a drop is visible.

The catalog gives each squad an owner and a status you can check from the terminal.

What Changes With squads-cli

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
• All squads in one command: squads run --all
• Scorecards and cost tracking built in

Each cycle, agents update their own state, propose changes to goals, and flag blockers. What carries over between runs is stored memory — files you can read, edit, and revert. Whether results improve is something the scorecard and run logs let you check.

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