> ## Documentation Index
> Fetch the complete documentation index at: https://v1.docs.meetsquad.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Squad via CLI

> Manage your product strategy directly from the terminal — optimised for AI agents

<Info>
  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.
</Info>

<Warning>
  **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](https://docs.meetsquad.ai).
</Warning>

## 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.

<Tabs>
  <Tab title="The problem with MCP">
    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
  </Tab>

  <Tab title="How CLI solves this">
    CLI commands use **\~200 tokens** per interaction — versus tens of thousands for equivalent MCP tool schemas. AI models have been trained on billions of lines of terminal interactions, making CLI a native language for them.

    * No schema overhead — agents already know how CLIs work
    * Composable via pipes, just like any Unix tool
    * JSON output mode for structured data when agents need it
    * Only uses tokens when you actually call a command
  </Tab>
</Tabs>

<Note>
  **When to use which:** Use the CLI when you're working with terminal-native agents or want maximum context efficiency. Use [MCP](/guides/squad-mcp) when you're working in Claude Desktop or prefer natural language tool discovery. Both connect to the same Squad data.
</Note>

## Prerequisites

<CardGroup cols={2}>
  <Card title="Squad Account" icon="user">
    Active Squad workspace with data
  </Card>

  <Card title="Node.js 22+" icon="js">
    Required runtime for the CLI
  </Card>
</CardGroup>

## Quick start

<Steps>
  <Step title="Install">
    <CodeGroup>
      ```bash npm theme={null}
      npm install -g @squadai/cli@^0.3
      ```

      ```bash npx (no install) theme={null}
      npx @squadai/cli@^0.3 auth login
      ```
    </CodeGroup>
  </Step>

  <Step title="Authenticate">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Select a workspace">
    ```bash theme={null}
    squad workspace list
    squad workspace select <orgId> <workspaceId>
    ```
  </Step>

  <Step title="Start using it">
    ```bash theme={null}
    squad opportunity list --format table
    squad goal list
    squad view roadmap
    ```
  </Step>
</Steps>

## 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          |

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

## Example workflows

<Accordion title="AI agent: strategy review in Claude Code">
  Add this to your project's `CLAUDE.md` to give Claude Code access to your product strategy:

  ```markdown theme={null}
  ## Product context
  Use `squad` CLI to access our product strategy.
  Run `squad workspace summary` for an overview.
  ```

  Then ask Claude Code:

  ```text theme={null}
  "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.
</Accordion>

<Accordion title="AI agent: feedback triage">
  ```text theme={null}
  "Check our latest feedback and create insights for any recurring themes"
  ```

  The agent runs:

  ```bash theme={null}
  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
  ```
</Accordion>

<Accordion title="Scripting: weekly strategy digest">
  ```bash theme={null}
  # Pull strategy data for a weekly report
  squad workspace summary
  squad view roadmap --format table
  squad feedback list | jq '.[] | select(.createdAt > "2026-03-11")'
  ```
</Accordion>

<Accordion title="AI agent: solution generation">
  ```text theme={null}
  "Look at our open opportunities and generate solutions for the highest priority one"
  ```

  The agent runs:

  ```bash theme={null}
  squad opportunity list
  # Identifies the top opportunity, then:
  squad opportunity generate-solutions <id>
  squad solution list --format table
  ```
</Accordion>

## 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

<Accordion title="Authentication fails">
  If the browser login doesn't complete:

  1. Make sure pop-ups aren't blocked in your browser
  2. Try signing into Squad at [meetsquad.ai](https://meetsquad.ai) first
  3. Check that you're using the correct Squad account
  4. Run `squad auth status` to check your current auth state
</Accordion>

<Accordion title="'No workspace selected' error">
  You need to select a workspace before running most commands:

  ```bash theme={null}
  squad workspace list          # Find your workspace
  squad workspace select <orgId> <workspaceId>
  ```

  Each environment (dev, staging, production) has its own workspace selection.
</Accordion>

<Accordion title="Token expired">
  Tokens refresh automatically. If you're still seeing auth errors:

  ```bash theme={null}
  squad auth logout
  squad auth login
  ```
</Accordion>

<Accordion title="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
</Accordion>

## Getting help

<CardGroup cols={2}>
  <Card title="npm package" icon="npm" href="https://www.npmjs.com/package/@squadai/cli">
    @squadai/cli on npm
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/the-basilisk-ai/squad-cli">
    Report issues or contribute
  </Card>

  <Card title="Squad MCP Guide" icon="plug" href="/guides/squad-mcp">
    Alternative: use Squad via MCP
  </Card>

  <Card title="Squad Support" icon="headset" href="https://meetsquad.ai">
    Contact the Squad team
  </Card>
</CardGroup>