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

# Squad CLI

> Install the Squad CLI, log in with OAuth, pick a workspace, and work the evidence chain from your terminal.

<img className="block dark:hidden" src="https://mintcdn.com/squad/O_98Wy8uNjlYcgBb/images/hero-cli-light.png?fit=max&auto=format&n=O_98Wy8uNjlYcgBb&q=85&s=376a19949a8f80f9f1a55ee1265ca3c1" alt="Squad CLI" width="2400" height="720" data-path="images/hero-cli-light.png" />

<img className="hidden dark:block" src="https://mintcdn.com/squad/O_98Wy8uNjlYcgBb/images/hero-cli-dark.png?fit=max&auto=format&n=O_98Wy8uNjlYcgBb&q=85&s=977b8225b9966581587b9eaeb4759d06" alt="Squad CLI" width="2400" height="720" data-path="images/hero-cli-dark.png" />

The Squad CLI puts signals, insights, actions, goals and decision briefs behind a `squad` binary. It speaks to the same API the web app uses, scoped to one workspace. Output is JSON by default, so pipe it into `jq` or hand it to a coding agent.

## Set up

<Steps>
  <Step title="Install the binary" icon="download">
    ```bash theme={null}
    npm install -g @squadai/cli
    ```

    Node.js 22 or newer. The binary installs as `squad`.

    Check it worked:

    ```bash theme={null}
    squad --version
    ```
  </Step>

  <Step title="Log in" icon="key-round">
    ```bash theme={null}
    squad auth login
    ```

    This opens your browser and runs an OAuth 2.1 authorization code flow with PKCE. The CLI registers itself as a public client against a loopback redirect, so nothing needs pre-configuring. Requested scopes are `read:workspace`, `write:workspace`, `openid` and `email`.

    The opaque token from that flow never talks to the API. The CLI exchanges it for a short-lived service JWT scoped to one organisation, then re-exchanges on its own when the JWT nears expiry.

    Check where you stand:

    ```bash theme={null}
    squad auth status
    ```

    It reports whether a session exists, when it expires, and whether it has already expired. `squad auth logout` clears the stored session and the workspace selection.
  </Step>

  <Step title="Pick a workspace" icon="folder-tree">
    Every command runs against one workspace. Login tries to pick one for you. If your identity reaches exactly one workspace, login selects it and says so. With more than one, login lists what it found and asks you to choose.

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

    `squad workspace list` prints the organisations and workspaces you can access, with the current selection marked. Pass the IDs from that output to `select`. The choice persists on disk, so you do this once per machine (or when you switch).

    <Note>
      Commands fail fast with `No workspace selected` until you have run `squad workspace select`. That holds even when you supply a token yourself.
    </Note>
  </Step>

  <Step title="Orient yourself" icon="compass">
    ```bash theme={null}
    squad workspace overview
    ```

    One call returns the mission statement, top goals, signal activity for the last seven days, evidence-chain health and open work counts. Start sessions here.
  </Step>
</Steps>

## Version compatibility

The `0.4.x` line targets the current Squad platform, the one behind [app.meetsquad.ai](https://app.meetsquad.ai). The `0.3.x` line targets the previous Squad product and speaks a different API. If your workspace is still on the older product, pin to the older line:

```bash theme={null}
npm install -g @squadai/cli@0.3.x
```

<Warning>
  Don't mix them. A `0.3.x` binary pointed at the current platform fails on every call.
</Warning>

## Configuration files

State lives in `~/.config/squad/`, or `$XDG_CONFIG_HOME/squad/` when that variable is set. The directory is created with `0700` and files with `0600`.

| File | Holds |
| - | - |
| `auth.json` | The OAuth session (access token, refresh token, expiry) and cached service JWTs |
| `client.json` | The OAuth client ID registered during login |
| `workspace.json` | The selected organisation and workspace |

<Warning>
  Treat `auth.json` as a credential. Deleting the directory is equivalent to `squad auth logout`.
</Warning>

## Global flags

| Flag | Effect |
| - | - |
| `--format <json\|table>` | Output format for list commands. Default `json`. |
| `--token <token>` | Use a service JWT instead of the stored session. |
| `--version` | Print the installed version. |
| `--help` | Print help for any command or subcommand. |

Commands that return a single record always print JSON.

## Headless and CI use

Set `SQUAD_TOKEN` to a service JWT to skip the browser flow. `--token` takes precedence over it. A workspace selection must already exist in the config directory, so run `squad workspace select` once on the machine (or ship a `workspace.json`) before automating.

## Where to go next

<CardGroup cols={3}>
  <Card title="Command reference" icon="square-terminal" href="/cli/commands">
    Thirty-three commands across thirteen areas, with their arguments and flags.
  </Card>

  <Card title="MCP server" icon="plug" href="/mcp/overview">
    The same capabilities inside an AI assistant rather than a shell.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.