# Plansmith CLI

Plan, spec, and push from your terminal. Zero dependencies, every command scriptable.



## Install and sign in [#install-and-sign-in]

```bash
npm install -g plansmith.co
plansmith auth
```

Signing in uses the device flow: the CLI shows a short code, your browser confirms it, and the CLI
receives a token bound to the workspace you picked.

<Callout>
  The package is published as `plansmith.co`; the binary it installs is `plansmith`.
</Callout>

## Everyday commands [#everyday-commands]

```bash
plansmith use recipe-box            # pin a default project
plansmith plan list                 # plans you can see
plansmith plan tree PLAN-12         # specs, sub-plans, dependencies
plansmith spec show PLAN-12/SPEC-3
plansmith context add ./notes.md --plan PLAN-12
plansmith plan status PLAN-12 READY
plansmith push PLAN-12 --to linear
```

A plan can be named three ways: fully qualified (`recipe-box/PLAN-12`), with `--project`, or bare
once you have pinned a default with `plansmith use`.

## Scripting [#scripting]

Every command takes `--json` and prints the API response unchanged, so your script depends on the
API rather than on how the CLI formats things. Human-facing output goes to stderr, so redirecting
stdout gives you clean data.

```bash
plansmith plan tree PLAN-12 --json | jq '.specs[] | .shortId + " " + .title'
```

## CI [#ci]

```bash
PLANSMITH_KEY=psk_read_… plansmith plan list -p recipe-box --json
```

A static key skips the saved session entirely and never refreshes, so CI behaves identically on
every run. Mint one with `plansmith keys create ci --scope read`.

## Environment [#environment]

```text
PLANSMITH_KEY          static API key (overrides the saved session)
PLANSMITH_API_URL      default https://api.plansmith.co
PLANSMITH_AUTH_URL     default https://www.plansmith.co
PLANSMITH_MCP_URL      default https://mcp.plansmith.co
PLANSMITH_CONFIG_DIR   default ~/.config/plansmith
```

<Callout>
  Pointing the CLI at a local server needs the `/api` segment:
  `PLANSMITH_API_URL=http://localhost:3000/api`. The `api.plansmith.co` host rewrites `/v1` onto it
  for you, and nothing else does.
</Callout>