> ## 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. Every command speaks to the same API the web app uses, scoped to one workspace, and prints JSON by default so you can 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 on your side. Requested scopes are `read:workspace`, `write:workspace`, `openid` and `email`.

    The opaque token from that flow is not what talks to the API. The CLI exchanges it for a short-lived service JWT scoped to one organisation, and re-exchanges when the JWT nears expiry. That exchange happens automatically.

    Check where you stand at any time:

    ```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 can reach exactly one workspace, it is selected automatically and login tells you 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 only do this once per machine (or when you want to 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>
  Mixing them does not work. 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. `--format table` applies to the list commands.

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