Documentation

Install

Node ≥ 20. The package has zero runtime dependencies and is published from GitHub Actions with npm provenance.

npm i -g @uxdata-co/kie
kie version
npm audit signatures   # optional: verify the tarball came from the repo

From source: clone julio-daza/kie-cli, then cd kie && npm install && npm run build && npm link.

API key

Create a dedicated key for agents at kie.ai/api-key and set hourly/daily caps plus an IP allow-list there — KIE enforces those even if this CLI is bypassed. KIE is prepaid: keep a modest balance.

• kie key set — paste the key, input is hidden.
• kie key check — source, masked key, validity, balance.
• kie key delete — remove it from the keystore.

kie key set
kie key check

Resolution order: KIE_API_KEY only when KIE_ALLOW_ENV_KEY=1 → the OS keystore (macOS Keychain service kie-cli · Windows DPAPI, user scope · Linux Secret Service via secret-tool) → ~/.config/kie/key (0600). KIE_DISABLE_KEYCHAIN=1 forces the file. System tools are called by absolute path and the secret never goes on a command line. The key never appears in stdout, stderr, the ledger or the config.

Commands

Generation commands wait for the task, download the result and settle the ledger unless you pass --no-wait.

Generation flags

Generic flags are mapped to each model's input fields by the catalog; --set passes any raw field through.

Model catalog

Aliases you type → KIE model ids. Only nano-banana-2 has a verified credit estimate; every other model requires --max-credits.

Any KIE Market model that is not in the catalog:

kie run <vendor>/<model> --input '{"prompt":"…"}' --max-credits 30 --dry-run
kie run <vendor>/<model> --input '{"prompt":"…"}' --max-credits 30

Spend guard & exit codes

Evaluated before any request leaves the machine. If it blocks, exit code is 3 and nothing was sent.

1. 01Per-task cap — models with a verified estimate are checked against maxCreditsPerTask; everything else needs an explicit --max-credits .
2. 02Daily budget — ~/.config/kie/ledger.jsonl records every task; on completion the real creditsConsumed is written back. Pending tasks count at their cap.
3. 03Balance — the estimate (or cap) must fit in the account's remaining credits.

Exit codes

Configuration

~/.config/kie/config.json (or $KIE_CONFIG_DIR). Read with kie config, change with kie config set .

kie config
kie config set dailyBudget 300

Agent skill (kie-media)

The package ships an Agent Skills–spec skill that teaches coding agents to use the CLI: check the budget first, images before video, always cap video spend, return file paths, never touch the key. One command installs it for the agents you use.

kie skill install                  # all four
kie skill install --agent claude   # one of: claude | codex | cursor | gemini
kie skill install --project        # into the current repo, for the team
kie skill install --force          # overwrite an older copy

Without the CLI: npx skills add julio-daza/kie-cli (skills.sh) installs the same folder for any supported agent.

MCP server (desktop apps)

Claude Desktop and the Codex app run the agent's shells in a sandbox — no PATH, no keystore, no network to api.kie.ai — so the skill cannot run there. kie mcp is a tools-only MCP server over stdio that the app spawns on your machine: the key stays in the keystore, the app only receives results, and generated images are returned inline so they show in the chat. It reuses the CLI's catalog, spend guard and ledger, so the daily budget is shared.

kie mcp install                # Claude Desktop + Codex + Cursor
kie mcp install --app claude   # one of: claude | codex | cursor
kie mcp config                 # print the JSON snippet for manual setup

• stdio only, on purpose: a network server holding a paid key is exactly what this project avoids.
• The config is written with the absolute Node binary and script path, because GUI apps do not inherit your shell PATH (nvm, volta…).
• Configs: macOS ~/Library/Application Support/Claude/claude_desktop_config.json, ~/.codex/config.toml, ~/.cursor/mcp.json. Restart the app after installing.
• Claude Code can use it too: claude mcp add kie -- /dist/src/index.js mcp (the skill is usually enough there).

Output contract

When stdout is a terminal you get tables, panels and a live spinner. When piped, or with --json, stdout is strictly JSON and messages go to stderr — that is what agents should use. --pretty forces the human view; --no-color or NO_COLOR disables ANSI.

kie image nano-banana-2 --prompt "…" --json
{
  "taskId": "task_…",
  "model": "nano-banana-2",
  "state": "success",
  "creditsConsumed": 8,
  "files": ["kie-media/nano-banana-2-c0ffee12.png"]
}

Security notes

• The CLI talks only to api.kie.ai, kieai.redpandaai.co (KIE's upload host) and the result URLs KIE returns.
• It never sends a callBackUrl; --set callBackUrl=… and --input {"callBackUrl":…} are rejected.
• Results are always downloaded — KIE URLs expire in ~24 h — and the CLI returns paths, not links.
• Uploads via kie upload land in KIE's temporary storage and are deleted after ~3 days.
• Report vulnerabilities privately through GitHub Security Advisories (see SECURITY.md).

FAQ