>unstuck engine

> The unstuck command line

@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_KEY in 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 status shows 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.