@unstuckengine/cli is the terminal door to the same operations the app, the
API and the MCP tools expose — and it ships the local MCP server (unstuck mcp).
The package README is the reference and lives with the code:
packages/cli/README.md (also the npm page).
When to use it
- Bulk reads into files or spreadsheets —
unstuck leads list --stage qualified --format csv > leads.csv. - Scripts and CI —
UNSTUCK_API_KEYin the environment,--format json(the default when piped), stable exit codes (0 ok · 1 platform error · 2 usage · 3 unreachable). - A local MCP server for clients that launch commands:
unstuck mcp. - Checking a connection —
unstuck auth statusshows which API URL and key are in effect, where each came from, and who the platform says you are.
Sixty-second start
npx @unstuckengine/cli auth login # paste a key from Settings → API keys (verified before it is stored)
npx @unstuckengine/cli whoami
npx @unstuckengine/cli signals list
npx @unstuckengine/cli leads list --q "acme" --has-email --page-size 50
npx @unstuckengine/cli tools # every command, and which ones an assistant sees over MCP
Install once instead of npx each time: npm i -g @unstuckengine/cli.
How flags relate to the API
Commands are generated from the same registry as the MCP tools and the
OpenAPI document: unstuck <group> <command> --help shows one
flag per API parameter, in kebab-case (--page-size ↔ page_size). Object
parameters take JSON inline, from a file (--config @file.json) or from stdin
(-); --args '<json>' sends the whole payload at once. The platform's own
error code, message and details are printed verbatim when a call is rejected —
the same text the API returns.
On Windows PowerShell, prefer --args @file.json (or - with
Get-Content file.json -Raw |) over inline JSON: npx.cmd strips the inner
double quotes. A byte order mark at the start of the file is tolerated (CLI
0.1.1+). Flags are two ASCII hyphens; a copied en dash (–status) is an
unknown option.
Configuration
~/.config/unstuck/config.json (%APPDATA%\unstuck\config.json on Windows;
UNSTUCK_CONFIG_DIR overrides). Precedence: flag → environment
(UNSTUCK_API_KEY, UNSTUCK_API_URL) → config file → built-in default. The
file is created by unstuck auth login with owner-only permissions; keys are
never printed.