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

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 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:
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 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.
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).
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:
Mixing them does not work. 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. --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

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.