pk-kaizen

A standalone command-line client for the Prompt Kaizen prompt-optimization API. It wraps the POST /api/v1/optimize and POST /api/v1/lint endpoints so you can optimize and audit prompts from your terminal and pipe the result into other tools.

pk is a thin client with zero runtime dependencies — it uses only the Node.js standard library and the native fetch API.

Requirements

• Node.js >= 18 (for native fetch, AbortSignal.timeout, and util.parseArgs).
• A Prompt Kaizen API key (format pk_<id>.<secret>). The server must have the API ingress enabled (API_ENABLED=true).

Install

Run without installing (recommended):

npx pk-kaizen --version

Or install globally:

npm install -g pk-kaizen
pk --version

Authentication

The CLI resolves your API key in this priority order:

1. The PK_API_KEY environment variable.
2. The stored config file (written by pk configure).

pk configure

Interactive (input is masked, never echoed):

pk configure
# Enter your API key: ********
# ✓ API key saved.

Non-interactive:

pk configure --key "pk_0123456789ab.your-secret"

Security note: passing --key puts the secret in your shell history and process list. Prefer the interactive prompt or the PK_API_KEY environment variable on shared machines.

The key is stored at $XDG_CONFIG_HOME/pk-kaizen/config.json (defaults to ~/.config/pk-kaizen/config.json) with 0600 permissions. The key is never printed back to you.

Use the environment variable to avoid storing anything on disk:

export PK_API_KEY="pk_0123456789ab.your-secret"

Usage

optimize is the default command, so pk and pk optimize are equivalent.

pk ping

Check that your API key is valid and see who it belongs to:

pk ping
# Key:     pk_abc123456def···
# SKU:     api_foundation
# Scopes:  optimize:write

Use --json to get the raw response, including your live API credit balance (apiCredits carries freeStandardRemaining, freeIntegrityRemaining, and paidCredits):

pk ping --json | jq .apiCredits

# Inline prompt
pk optimize --prompt "write a function that reverses a string" --mode coding

# From a file
pk optimize --file ./prompt.txt --mode general

# From stdin (pipe)
echo "explain recursion to a child" | pk --mode educational
cat prompt.txt | pk > optimized.txt

Prompt source priority: --file > --prompt/-p > stdin.

By default only the optimized prompt is written to stdout — all spinners, scores, and diagnostics go to stderr, so piping stays clean. Use --json to get the full API response on stdout instead. On any error path (including pipeline failure), nothing is written to stdout; the reason is printed to stderr and the process exits non-zero.

New keys start with a one-time free grant of standard and integrity runs. After that, a standard pk optimize call costs 1 credit and an --integrity run costs 5 credits from your API balance. Use pk ping --json to check your balance at any time. When you're out of credits the server returns HTTP 402 and the CLI exits with a clear message.

Options (pk optimize)

| Flag | Description | Default | | --- | --- | --- | | -p, --prompt <text> | Inline prompt text | — | | --file <path> | Read the prompt from a file | — | | --mode <mode> | One of general, coding, creative, enterprise, educational | general | | --json | Print the full JSON response to stdout | off | | --show-score | Print the prompt strength score to stderr | off | | --integrity | Request the integrity engine and print its report to stderr (pay-as-you-go; costs more credits) | off | | --base-url <url> | API base URL | https://promptkaizen.com | | --timeout <seconds> | Request timeout in seconds | 60 | | -h, --help | Show command help | — |

Global flags

| Flag | Description | | --- | --- | | -V, --version | Print the CLI version (to stdout) | | -h, --help | Show help |

Examples

# Pipe the optimized prompt straight into another tool
echo "summarize this PR" | pk --mode coding | pbcopy

# Inspect the full response including prompt strength
pk -p "draft a launch email" --mode enterprise --json | jq .promptStrength

# See the score without polluting stdout
pk -p "a haiku about winter" --mode creative --show-score > out.txt

# Run the integrity engine; the optimized prompt goes to out.txt while the
# integrity report (verdict, findings, fabrication alerts) prints to stderr
pk -p "explain our refund policy" --mode enterprise --integrity > out.txt

Integrity reports

--integrity asks the server to run the integrity engine. It is pay-as-you-go — any key can request it (an integrity run costs more credits than a standard run). The optimized prompt still goes to stdout; the integrity report is printed to stderr so piping stays clean. The report includes:

• Verdict — pass, findings_detected, or review_recommended. The engine detects and flags issues for you to review — it does not block, prevent, or guarantee anything.
• Reason — the gating/recommendation rationale.
• Fabrication alerts — claims the engine flags as potentially invented.
• Findings — adversary issues with their severity, category, description, optional location, and suggestion.

With --json, the integrity block is part of the JSON payload on stdout instead of being formatted to stderr. If a key's plan does not include integrity, the server silently runs the standard pipeline instead, and the CLI notes that no integrity report was returned.

pk lint

Audit a raw prompt for inherent quality defects — a single-pass check of the prompt as written, with no rewrite or optimization. Lint is free (it does not draw from your credit balance) and is metered by its own monthly quota.

# From a file (positional argument)
pk lint ./prompt.txt

# From stdin
pk lint -
cat prompt.txt | pk lint

# Pick a mode and fail CI on warnings
pk lint ./prompt.txt --mode coding --fail-on warning

# Full JSON for tooling
pk lint ./prompt.txt --json

The prompt source is a positional file path (or - / piped stdin) — there is no --file flag for pk lint. Findings are written to stdout (or JSON with --json); progress and errors go to stderr.

Options (pk lint)

| Flag | Description | Default | | --- | --- | --- | | --mode <mode> | One of general, coding, creative, enterprise, educational | general | | --verbose | Include suggestion-level findings | warning+ | | --fail-on <level> | Exit 1 when findings reach this level: critical, warning, suggestion, or none | critical | | --json | Print the full JSON response to stdout | off | | --no-color | Disable ANSI colors in stdout findings | off | | --base-url <url> | API base URL | https://promptkaizen.com | | --timeout <seconds> | Request timeout in seconds | 60 | | -h, --help | Show command help | — |

pk lint does not accept --integrity; for integrity analysis use pk optimize --integrity.

Exit codes (pk lint)

| Code | Meaning | | --- | --- | | 0 | No findings at or above the --fail-on threshold | | 1 | Findings at or above the threshold (or missing API key) | | 2 | Tool failure (file not found, network error, bad response) |

Exit codes (pk optimize / pk ping)

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | Any error (missing key, auth failure, rate/quota limit, API disabled, pipeline failure, validation error, network error, timeout, malformed response) | | 130 | Interrupted with Ctrl+C (SIGINT) |

Error handling

Every failure path prints a clear message to stderr and exits non-zero:

• No API key — run pk configure or set PK_API_KEY.
• 401 — invalid, missing, or revoked key.
• 402 — out of credits. A standard run costs 1 credit and an --integrity run costs 5. Use pk ping --json to check your balance before running a batch. Top up at https://promptkaizen.com/pricing.
• 429 — quota or concurrency limit reached; the message includes the live quota/concurrency numbers from the response headers.
• 503 — the free API tier is paused for the day (global daily limit reached); add credits to keep going, or retry after the UTC daily reset.
• API not available — the server returned non-JSON/HTML (or 404), which usually means API_ENABLED is not set to true on the server.
• Pipeline failure — the API returned HTTP 200 with a pipelineFailure object; the human-readable reason is shown.
• Network error / timeout — connection failed or exceeded --timeout.
• Malformed JSON — the server response could not be parsed.

Development

cd cli
npm install        # installs devDependencies (typescript, tsx, @types/node)
npm run dev -- --version   # run from TypeScript source via tsx
npm run build      # compile src/ -> dist/

The build emits CommonJS to dist/. The published package ships only dist/ and this README.