Skip to main content
Squad CLI 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

Install the binary

Node.js 22 or newer. The binary installs as squad.Check it worked:

Log in

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

Pick a workspace

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.
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).
Commands fail fast with No workspace selected until you have run squad workspace select. That holds even when you supply a token yourself.

Orient yourself

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.

​
Version compatibility

The 0.4.x line targets the current Squad platform, the one behind 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:
Don’t mix them. A 0.3.x binary pointed at the current platform fails on every call.

​
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.
Treat auth.json as a credential. Deleting the directory is equivalent to squad auth logout.

​
Global flags

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

Command reference

Thirty-three commands across thirteen areas, with their arguments and flags.

MCP server

The same capabilities inside an AI assistant rather than a shell.