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 → macOS Keychain (service kie-cli) → ~/.config/kie/key (0600). KIE_DISABLE_KEYCHAIN=1 forces the file. 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.

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