Promethic CLI

Agent + terminal access to the Promethic public API.

Install

npm install -g @soulwarestudio/promethic-cli

Quickstart

# Get a key from https://app.getpromethic.com → Settings → Developer Keys
promethic auth login                                # paste pmk_… key

promethic prompts list                              # see your prompts
promethic prompts get <prompt-id>                   # full prompt + current version

# Run a prompt. V1.2 default: auto-finalizes on success (a record is
# saved automatically; recordId is printed alongside the runId).
promethic run <prompt-id> --input "summarize this article"

# Revise: pass either a runId (active session) OR a recordId (rehydrate
# from a finalized record's snapshot). V1.2 collapsed `revise-again`
# into `revise`.
promethic revise <run-id-or-record-id> --instruction "tighten by 30%"

# Manual finalize (only needed if you ran with --auto-finalize false,
# OR you want to add notes / a tag / edit the final text).
promethic finalize <run-id> --notes "approved" --tag "polish-pass-1"

# Records
promethic records list --limit 20
promethic records get <record-id>
promethic records image <record-id> --index 0 --output out.png

V1.2 highlights (CLI 0.6.0+)

• Auto-finalize on run — by default, a successful run saves a record. The CLI prints both runId AND recordId to stderr. Pass --auto-finalize false to keep the run as an unfinalized session you'll explicitly promethic finalize later.
• revise <handle> accepts run-id OR record-id — rehydrate from a finalized record without running through revise-again (which is gone). Server-side per-record advisory lock serializes concurrent rehydrate attempts.
• --from-turn N rewind — on revise AND finalize, drops session turns beyond N before applying the operation. finalize --from-turn N on a finalized session reopens, bumps generation, and re-finalizes (amend semantic).
• Three new SSE events surface in MCP tool replies: record_finalized (carries recordId after auto-finalize), record_finalize_failed (chained finalize broke; agent decides whether to retry manually), and record_finalize_skipped (informational; never branch failure handling on it).
• MCP tool count: 24 (revise_again collapsed into revise_run).

See https://api.getpromethic.com/agent-api-v1.html for the full V1.2 changelog.

Auth

Credentials live at ~/.promethic/credentials (mode 0600) on macOS/Linux, %APPDATA%\Promethic\credentials on Windows.

promethic auth status runs a connectivity probe against /api/v2/public/prompts?limit=1.

promethic auth login puts the terminal into raw mode and reads the key without echoing it. Each pasted/typed character emits a single * for visual progress; backspace works; Ctrl-C aborts. The key never lands in shell scrollback. When stdin is piped (echo "pmk_..." | promethic auth login), raw mode is skipped and the key is read line-mode — no echo concern since the bytes never reach a terminal. Use this form for CI / automation where a secret store provides the key.

API URL override

export PROMETHIC_API_URL=http://localhost:8080
promethic auth status

Security: PROMETHIC_API_URL MUST be https://... or http://localhost / http://127.0.0.1 for dev. The CLI refuses to send your API key to other http:// hosts (prevents accidental key leak via typo'd or hostile env var).

Default: https://api.getpromethic.com.

Exit codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | User error (bad args, missing flags) | | 2 | Auth error (no key / expired / scope mismatch) | | 3 | Rate limited (429) | | 4 | Server error (5xx, network) |

SSE protocol

run, revise are streaming endpoints. The CLI parses:

| Event | Meaning | |-------|---------| | run_session | First. Carries runId, turnIndex, protocolVersion. | | (upstream) | OpenAI events pass through to stdout. | | run_completed | Success terminator. Reports costMicros. | | record_finalized | V1.2. Auto-finalize succeeded. Carries recordId, turns, costMicros. | | record_finalize_failed | V1.2. Chained finalize broke; carries reasonCode + retryable. The run itself succeeded. | | record_finalize_skipped | V1.2 informational; emitted after run_failed when --auto-finalize was set. Don't branch failure handling on it. | | run_failed | Failure terminator. Reports reasonCode, charged, costMicros, usageLogId. | | run_replayed | Returned on Idempotency-Key replay. Tells the caller to poll. |

Unknown event names are ignored (forward-compat). The CLI warns if the server reports a higher protocol version.

Run lifecycle

V1.2 default: run auto-finalizes. The CLI prints both runId and recordId to stderr after streaming completes. --auto-finalize false keeps the run as an unfinalized session — then revise with the runId and finalize manually when ready.

--no-accept saves a JSON artifact at ~/.promethic/runs/<runId>.json (mode 0600) so the runId + state survives across shell sessions and is discoverable for later finalize/abandon. Useful for long-running agent workflows where the run + finalize happen at different times.

Claude Desktop integration (MCP)

Promethic ships a local-stdio MCP (Model Context Protocol) server. Adding 4 lines to claude_desktop_config.json gives Claude Desktop (and any MCP-aware desktop client: Cursor, Zed, Continue, Cline) 24 tools mirroring the Promethic workspace flow:

• read (8): list_prompts, get_prompt, list_records, list_versions, get_version, list_attachments, get_attachment, get_catalog
• execute (5): run_prompt (V1.2: autoFinalize parameter), revise_run (V1.2: accepts runId XOR recordId; supports fromTurn), finalize_run (V1.2: supports fromTurn), abandon_run, get_run_image
• write (10): create_prompt, update_prompt, delete_prompt, create_version, update_version, switch_current_version, delete_version, delete_record, upload_attachment, delete_attachment
• utility: patch_record

Quick start

1. npm install -g @soulwarestudio/promethic-cli

2. promethic auth login (paste your pmk_… key).

3. promethic mcp --probe — smoke test. If it prints Probe: OK, MCP will work.

4. Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

   {
     "mcpServers": {
       "promethic": {
         "command": "promethic",
         "args": ["mcp"]
       }
     }
   }

5. Restart Claude Desktop. The Promethic tools appear in the tool tray.

Per-MCP-install API key override

For sandboxed installs or different keys per Claude Desktop profile, pass the key as an env var:

{
  "mcpServers": {
    "promethic": {
      "command": "promethic",
      "args": ["mcp"],
      "env": {
        "PROMETHIC_API_KEY": "pmk_…"
      }
    }
  }
}

PROMETHIC_API_KEY env wins over ~/.promethic/credentials for every CLI invocation, MCP or otherwise.

Tool replies

Every tool returns a structured JSON envelope:

• Success: {"ok": true, ...} — e.g., {"ok": true, "prompts": [...]}. V1.2 run_prompt with auto-finalize success surfaces recordId + autoFinalized: true directly on the reply.
• Business failure: {"ok": false, "reasonCode": "rate_limited", "retryAfterSeconds": 42, "apiVersion": "1", ...} — isError stays unset; the agent reasons over reasonCode directly.
• Transport / 5xx / malformed-args: {"ok": false, "reasonCode": "transport_error", ...} with isError: true.

V1.2 chained-finalize failure surfaces as {"ok": true, ..., "autoFinalizeFailed": {"reasonCode": "...", "retryable": true}} — the run itself succeeded; the chain is what broke. Agents inspect autoFinalizeFailed.retryable to decide whether to call finalize_run manually.

Image-modality runs

For prompts with image output, run_prompt and revise_run fetch each generated image from GET /api/v2/public/runs/{runId}/images/{N} after run_completed. Images ≤ 16 MB raw return inline as base64; larger images go to ~/.promethic/runs/<runId>/image-<N>.png (or %LOCALAPPDATA%\Promethic\runs\… on Windows) and return as {inline: false, localPath, mimeType}. Local files persist for the MCP server process lifetime; stale <runId> directories older than 24h are swept on MCP startup.

get_run_image is the explicit fetch when an agent wants a specific index in isolation.

Cancellation

If the agent cancels a tool call mid-stream, the MCP server destroys the SSE connection and calls POST /runs/{runId}/abandon so the RunSession is released within ~1s instead of waiting for the 5-min stall timeout. Benign cancellation races (409 run_already_terminal, 404, etc.) are silently absorbed.

Roadmap

A hosted MCP server is coming so iOS-class clients (Claude iOS, ChatGPT iOS) and web-class agents (claude.ai web) — which can't run a local stdio server — can speak Promethic MCP without installing the CLI. Endpoint: mcp.getpromethic.com/v1. Plans: HOSTED_MCP.md.

The local-stdio CLI MCP this README documents will continue to work indefinitely.

Docs

Full agent API docs: https://api.getpromethic.com/agent-api-v1.html.

Changelog: CHANGELOG.md.