Using Squad via CLI

Squad CLI gives terminal-native AI agents like Claude Code, Codex, and OpenCode direct access to your product strategy without the context window overhead of MCP. Same tools, fraction of the tokens.

Version compatibility: These are the v1 (legacy) Squad docs, which track Squad CLI v0.3.x. Pin to this line when installing — @squadai/cli@^0.3. CLI v0.4 and later target the new v2 Squad and aren’t compatible with v1; for those, see the current docs.

Overview

Squad CLI (@squadai/cli) is a command-line tool for managing your entire product strategy from the terminal. It supports all the same operations as Squad’s MCP server — goals, opportunities, solutions, feedback, insights, knowledge, and more — but through simple, composable commands that AI agents already know how to use.

Why CLI over MCP?

More builders than ever are shipping code using terminal-native agents like Claude Code, Codex, and OpenCode. But MCP servers can quietly eat through your context window before your agent even starts working.

The problem with MCP
How CLI solves this

MCP servers inject their full tool schemas into every conversation. A typical MCP server consumes tens of thousands of tokens just for tool definitions — tokens your agent could be using to reason about your actual problem.With multiple MCP servers connected, you can lose over 150,000 tokens of context before your agent processes a single task.

Tool schemas are loaded upfront, whether you use them or not
Each MCP call returns structured JSON that the model must parse
Complex workflows require multiple round-trips with state management overhead

When to use which: Use the CLI when you’re working with terminal-native agents or want maximum context efficiency. Use MCP when you’re working in Claude Desktop or prefer natural language tool discovery. Both connect to the same Squad data.

Prerequisites

Squad Account

Active Squad workspace with data

Node.js 22+

Required runtime for the CLI

Quick start

Install

npm install -g @squadai/cli@^0.3

npx @squadai/cli@^0.3 auth login

Authenticate

squad auth login

This opens your browser for secure OAuth login. Your credentials are never stored locally — only a scoped access token that refreshes automatically.

Select a workspace

squad workspace list
squad workspace select <orgId> <workspaceId>

Start using it

squad opportunity list --format table
squad goal list
squad view roadmap

Command reference

Authentication

Command	Description
`squad auth login`	Log in via browser (OAuth2 PKCE)
`squad auth logout`	Clear stored credentials
`squad auth status`	Show auth status and token expiration

Workspaces

Command	Description
`squad workspace list`	List all available workspaces
`squad workspace select <orgId> <workspaceId>`	Set active workspace
`squad workspace get`	Get current workspace details
`squad workspace summary`	View pre-rendered strategy summary
`squad workspace update`	Update workspace name, description, mission, or URLs

Goals

Command	Description
`squad goal list`	List all business goals
`squad goal get <id>`	Get goal details (with optional relationships)
`squad goal create --title <title>`	Create a new goal
`squad goal update <id>`	Update a goal
`squad goal delete <id>`	Delete a goal
`squad goal relationships <id>`	Manage goal-to-opportunity relationships

Opportunities

Command	Description
`squad opportunity list`	List all opportunities
`squad opportunity get <id>`	Get opportunity details
`squad opportunity create --title <title> --description <desc>`	Create an opportunity
`squad opportunity update <id> [--title <title>] [--description <desc>] [--status <status>]`	Update an opportunity
`squad opportunity delete <id>`	Delete an opportunity
`squad opportunity generate-solutions <id>`	Generate AI solutions for an opportunity
`squad opportunity relationships <id>`	Manage relationships to solutions, goals, and insights

Solutions

Command	Description
`squad solution list`	List all solutions
`squad solution get <id>`	Get solution details
`squad solution create --title <title> --description <desc>`	Create a solution
`squad solution update <id> [--title <title>] [--description <desc>] [--status <status>]`	Update a solution
`squad solution delete <id>`	Delete a solution
`squad solution edit-prd <id> --content <content>`	Edit a solution’s PRD
`squad solution relationships <id>`	Manage relationships
`squad solution prioritise --solution-ids <ids>`	Reorder solutions

Feedback

Command	Description
`squad feedback list`	List all feedback
`squad feedback get <id>`	Get feedback details
`squad feedback create --content <content> --source <source> [--title <title>]`	Submit feedback
`squad feedback delete <id>`	Delete feedback

Insights

Command	Description
`squad insight list`	List all insights
`squad insight get <id>`	Get insight details
`squad insight create --title <title> --description <desc> --type <type>`	Create an insight (`Feedback`, `Bug`, or `FeatureRequest`)
`squad insight delete <id>`	Delete an insight

Knowledge

Command	Description
`squad knowledge list`	List all knowledge items
`squad knowledge get <id>`	Get a knowledge item
`squad knowledge create --title <title> --description <desc> --content <content>`	Create a knowledge item
`squad knowledge delete <id>`	Delete a knowledge item

Search

Command	Description
`squad search <query>`	Semantic search across your workspace

Optional: --filters <sources> to limit by knowledge-base, insights, opportunities, or solutions.

Strategy views

Command	Description
`squad view strategy-context`	View entity in the strategy hierarchy
`squad view roadmap`	View solutions by time horizon (Now / Next / Later)

Options for strategy-context: --type <workspace|goal|opportunity|solution>, --id <id> Options for roadmap: --goal-id <id>, --status <statuses>, --show-resolved

Global options

All commands support these flags:

Flag	Description
`--format <json\|table>`	Output format (default: `json`)
`--env <dev\|staging\|production>`	Target environment (default: `production`)
`--token <token>`	Override stored auth with a token

Use --format json (the default) when working with AI agents. Use --format table for human-readable output in your terminal.

Example workflows

AI agent: strategy review in Claude Code

Add this to your project’s CLAUDE.md to give Claude Code access to your product strategy:

## Product context
Use `squad` CLI to access our product strategy.
Run `squad workspace summary` for an overview.

Then ask Claude Code:

"Review our product strategy and identify gaps between goals and active solutions"

Claude Code will run commands like squad goal list, squad opportunity list, and squad view strategy-context to build a complete picture — using a fraction of the tokens MCP would require.

AI agent: feedback triage

"Check our latest feedback and create insights for any recurring themes"

The agent runs:

squad feedback list
# Analyzes patterns, then:
squad insight create --title "Users reporting slow load times" \
  --description "12 feedback items mention page load >5s" \
  --type Feedback

Scripting: weekly strategy digest

# Pull strategy data for a weekly report
squad workspace summary
squad view roadmap --format table
squad feedback list | jq '.[] | select(.createdAt > "2026-03-11")'

AI agent: solution generation

"Look at our open opportunities and generate solutions for the highest priority one"

The agent runs:

squad opportunity list
# Identifies the top opportunity, then:
squad opportunity generate-solutions <id>
squad solution list --format table

Configuration

Squad CLI stores configuration in ~/.config/squad/ (respects XDG_CONFIG_HOME):

File	Purpose
`auth.json`	OAuth tokens per environment
`client.json`	Registered OAuth client IDs
`workspace.json`	Selected workspace per environment

You can also set the SQUAD_TOKEN environment variable to override stored authentication, and SQUAD_ENV to select an environment without passing --env.

Troubleshooting

Authentication fails

If the browser login doesn’t complete:

Make sure pop-ups aren’t blocked in your browser
Try signing into Squad at meetsquad.ai first
Check that you’re using the correct Squad account
Run squad auth status to check your current auth state

'No workspace selected' error

You need to select a workspace before running most commands:

squad workspace list          # Find your workspace
squad workspace select <orgId> <workspaceId>

Each environment (dev, staging, production) has its own workspace selection.

Token expired

Tokens refresh automatically. If you’re still seeing auth errors:

squad auth logout
squad auth login

Rate limiting

If you see rate limit errors:

Squad allows 100 requests per minute
Wait 60 seconds if you hit limits
Consider upgrading your Squad plan for higher limits

Getting help

npm package

@squadai/cli on npm

GitHub

Report issues or contribute

Squad MCP Guide

Alternative: use Squad via MCP

Squad Support

Contact the Squad team

Introduction

Guides

Features

Integrations

Overview

Why CLI over MCP?

Prerequisites

Squad Account

Node.js 22+

Quick start

Command reference

Authentication

Workspaces

Goals

Opportunities

Solutions

Feedback

Insights

Knowledge

Search

Strategy views

Global options

Example workflows

Configuration

Troubleshooting

Getting help

npm package

GitHub

Squad MCP Guide

Squad Support

​Overview

​Why CLI over MCP?

​Prerequisites

Squad Account

Node.js 22+

​Quick start

​Command reference

​Authentication

​Workspaces

​Goals

​Opportunities

​Solutions

​Feedback

​Insights

​Knowledge

​Search

​Strategy views

​Global options

​Example workflows

​Configuration

​Troubleshooting

​Getting help

npm package

GitHub

Squad MCP Guide

Squad Support

Overview

Why CLI over MCP?

Prerequisites

Quick start

Command reference

Authentication

Workspaces

Goals

Opportunities

Solutions

Feedback

Insights

Knowledge

Search

Strategy views

Global options

Example workflows

Configuration

Troubleshooting

Getting help