Documentación

Instalación

Node ≥ 20. El paquete tiene cero dependencias en runtime y se publica desde GitHub Actions con provenance de npm.

npm i -g @uxdata-co/kie
kie version
npm audit signatures   # opcional: verifica que el tarball salió del repo

Desde el código: clona julio-daza/kie-cli y luego cd kie && npm install && npm run build && npm link.

API key

Crea una key dedicada para agentes en kie.ai/api-key y ponle ahí topes por hora/día más una lista blanca de IPs — KIE los aplica aunque alguien se salte esta CLI. KIE es prepago: mantén un saldo moderado.

• kie key set — pega la key, la entrada está oculta.
• kie key check — origen, key enmascarada, validez, saldo.
• kie key delete — la elimina del almacén.

kie key set
kie key check

Orden de resolución: KIE_API_KEY solo con KIE_ALLOW_ENV_KEY=1 → Keychain de macOS (servicio kie-cli) → ~/.config/kie/key (0600). KIE_DISABLE_KEYCHAIN=1 fuerza el archivo. La key nunca aparece en stdout, stderr, el ledger ni la config.

Comandos

Los comandos de generación esperan la tarea, descargan el resultado y cierran el ledger, salvo que pases --no-wait.

Flags de generación

El catálogo traduce los flags genéricos a los campos de entrada de cada modelo; --set pasa cualquier campo crudo.

Catálogo de modelos

Alias que escribes → ids de modelo en KIE. Solo nano-banana-2 tiene estimación de créditos verificada; el resto exige --max-credits.

Cualquier modelo del Market de KIE que no esté en el catálogo:

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

Guardia de gasto y códigos de salida

Se evalúa antes de que cualquier request salga de la máquina. Si bloquea, el código de salida es 3 y no se envió nada.

1. 01Tope por tarea — los modelos con estimación verificada se comparan con maxCreditsPerTask; el resto necesita un --max-credits explícito.
2. 02Presupuesto diario — ~/.config/kie/ledger.jsonl registra cada tarea; al completarse se escribe el creditsConsumed real. Las pendientes cuentan por su tope.
3. 03Saldo — la estimación (o el tope) debe caber en los créditos restantes de la cuenta.

Códigos de salida

Configuración

~/.config/kie/config.json (o $KIE_CONFIG_DIR). Se lee con kie config y se cambia con kie config set .

kie config
kie config set dailyBudget 300

Skill de agente (kie-media)

El paquete incluye un skill (spec Agent Skills) que enseña a los agentes de código a usar la CLI: revisar el presupuesto primero, imágenes antes que video, siempre acotar el gasto en video, devolver rutas de archivo y nunca tocar la key. Un comando lo instala para los agentes que uses.

kie skill install                  # los cuatro
kie skill install --agent claude   # uno de: claude | codex | cursor | gemini
kie skill install --project        # en el repo actual, para el equipo
kie skill install --force          # sobrescribe una copia vieja

Sin la CLI: npx skills add julio-daza/kie-cli (skills.sh) instala la misma carpeta para cualquier agente soportado.

Contrato de salida

Si stdout es una terminal ves tablas, paneles y un spinner en vivo. Con pipe, o con --json, stdout es estrictamente JSON y los mensajes van a stderr — eso es lo que deben usar los agentes. --pretty fuerza la vista humana; --no-color o NO_COLOR quita el 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"]
}

Notas de seguridad

• La CLI solo habla con api.kie.ai, kieai.redpandaai.co (host de subida de KIE) y las URLs de resultado que KIE devuelve.
• Nunca envía callBackUrl; --set callBackUrl=… y --input {"callBackUrl":…} se rechazan.
• Los resultados siempre se descargan — las URLs de KIE expiran en ~24 h — y la CLI devuelve rutas, no enlaces.
• Las subidas con kie upload van al almacenamiento temporal de KIE y se borran a los ~3 días.
• Reporta vulnerabilidades en privado por GitHub Security Advisories (ver SECURITY.md).

Preguntas frecuentes