Promethic CLI

Script Promethic from your terminal or CI.

What it's for. Promethic is a prompt manager that versions, runs, and refines your prompts. Most people drive it from the desktop or web app. This CLI is the headless, scriptable path: shell pipelines that run prompts, CI jobs that author/version prompts and seed training records, and anything that wants a pmk_ API key instead of an interactive login. Every command speaks --json.

For AI agents, use the hosted MCP — not this CLI. Connect mcp.getpromethic.com/v1 with your pmk_ key as a Bearer header: remote, OAuth, zero-install, and it exposes the full agent tool surface (including per-prompt tools). The CLI's local MCP server was retired in 0.7.0 — there is one MCP now, and it's the hosted one. The CLI is for humans and scripts.

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 (or set PROMETHIC_API_KEY)

promethic catalog                          # model_ids you can build prompts with
promethic prompts list                     # your prompts
promethic prompts get <prompt-id>          # full prompt + current version

# Run a prompt. Default: auto-finalizes on success (a record is saved; the
# recordId prints alongside the runId). --json emits a machine-readable summary.
promethic run <prompt-id> --input "summarize this article" --json

# Revise an active run (or a finalized record), then finalize with a correction.
promethic revise <run-id> --instruction "tighten by 30%"
promethic finalize <run-id> --notes "approved" --tag "Lead with the ask"

Commands

auth        login · status · logout
catalog     [modelId]                       # GET /models — pick a model_id
prompts     list · get · create · patch · switch-current · delete · delete-version
versions    list · get · create · update    # update = metadata only (see below)
records     list · get · create · patch · delete · image
run · revise · finalize · abandon
attachments add · list · get · delete
config      list · get · set · unset         # session-auth only — see note

Run promethic <group> --help for flags. Highlights:

• catalog [modelId] — list active models (model_id, capabilities); pass a model_id for its full parameter detail. Feed model_id into prompts create --model-settings '{"model_id":"…","parameters":{…}}'.
• records create <promptId> — seed a manual (input → output) training pair with no LLM call and no spend. The prompts-as-code / CI seeding path. Idempotent on --idempotency-key. Text-modality prompts only.
• records patch <id> — set --notes/--tag, rewrite --output/--input, or --from-turn N to revert to an earlier turn. --tag is a generalizable rule (e.g. "Less formal"), not a description of the diff — it feeds the desktop Refine-Prompt feature.
• versions update — patches version metadata only (--version-description, --description, --description-mode). promptText and model settings are immutable per version by design; create a new version (versions create) for a behavioral change. Use --if-match <token> (the ifMatchToken from versions get --json) for safe concurrent edits; omit it for last-write-wins.
• Capability descriptions live on the version, not the prompt. Set them with versions update --description; prompts create/patch have no description field.

CI / scripting example

export PROMETHIC_API_KEY="pmk_…"            # non-interactive auth for CI

ID=$(promethic prompts create --name "Tagline" \
       --prompt-text "Write a punchy one-line tagline for: {{input}}" \
       --model-settings '{"model_id":"gpt-5.1-mini","parameters":{"reasoning_effort":"low"}}' \
       --json | jq -r .prompt.id)

OUT=$(promethic run "$ID" --input "a calendar app for dogs" --json | jq -r .outputText)
echo "$OUT"

# Seed a curated example for later prompt-refinement (no LLM call):
promethic records create "$ID" --input "a calendar app for dogs" \
  --output "Never miss a walk again." --idempotency-key "seed-dogs-1"

Auth

Credentials live at ~/.promethic/credentials (mode 0600) on macOS/Linux, %APPDATA%\Promethic\credentials on Windows. PROMETHIC_API_KEY env wins over the saved file — use it for CI.

promethic auth login reads the key without echoing it (raw mode; single * per char; Ctrl-C aborts). When stdin is piped (echo "pmk_…" | promethic auth login), it reads line-mode for automation.

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

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 (dev). The CLI refuses to send your API key to other http:// hosts. 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)

run and revise stream Server-Sent Events. The CLI parses:

| Event | Meaning | |-------|---------| | run_session | First. Carries runId, turnIndex, protocolVersion. | | (upstream) | Model output events pass through to stdout. | | run_completed | Success terminator. Reports costMilliCents. | | record_finalized | Auto-finalize succeeded. Carries recordId. | | record_finalize_failed | Chained finalize broke (the run itself succeeded); carries reasonCode + retryable. | | record_finalize_skipped | Informational; emitted after run_failed when auto-finalize was set. Don't branch failure handling on it. | | run_failed | Failure terminator. Reports reasonCode, charged, costMilliCents. |

Unknown event names are ignored (forward-compat); the CLI warns on a higher server protocol version.

Run lifecycle

Default: run auto-finalizes — the CLI prints both runId and recordId after the stream completes. --no-auto-finalize keeps the run as an unfinalized session; revise with the runId, then finalize when ready. --no-accept saves a JSON artifact at ~/.promethic/runs/<runId>.json (mode 0600) so the runId survives across shells for a later finalize/abandon.

A note on config

The config commands read/write user-level cloud settings via /api/v2/settings, which requires a session token (the desktop/web login), not a pmk_ API key. With only an API key configured, config prints a clear message and exits non-zero. Manage these settings from the desktop or web app; the rest of the CLI is fully pmk_-key driven.

Docs

Full public API reference: https://api.getpromethic.com/agent-api-v1.html. Hosted MCP for agents: https://getpromethic.com/agents. Changelog: CHANGELOG.md.