CLI de Koywe

El CLI de Koywe (@koyweforest/cli) cubre cada operación de la API de la Plataforma Koywe: cuentas, órdenes, cotizaciones, deals, contactos, webhooks, policy, reportes y más.

Está diseñado tanto para desarrolladores humanos como para agentes de IA (Claude Code y similares). Cada comando devuelve un envelope JSON estructurado, la mayoría de comandos mutadores aceptan --schema para imprimir el esquema JSON completo del cuerpo de solicitud, y el CLI expone su propio catálogo de comandos vía --commands.

¿Buscas el catálogo completo? Cada comando está listado en la Referencia de Comandos CLI, generada directamente desde los metadatos del CLI — ejecuta npx @koyweforest/cli --commands para el JSON crudo. O invierte el índice: la Referencia Cruzada API ↔ CLI te permite buscar un comando CLI por endpoint REST.

Instalar o ejecutar

La forma más rápida de empezar — sin instalar nada:

npx @koyweforest/cli --help

npx es lo que normalmente querrás en CI, agentes sandboxed, y terminales de un solo uso — fija la versión por invocación y no deja rastro.

Para uso local habitual, instala globalmente y usa el alias corto koywe:

npm install -g @koyweforest/cli
koywe --help

Requiere Node.js >= 18.

El resto de esta página usa koywe … para mantener los ejemplos legibles. Si no instalaste globalmente, lee cada koywe como npx @koyweforest/cli.

Arranque rápido para agentes

De cero a primera orden en tres comandos:

koywe init                 # Login por navegador + auto-creación de credenciales API
koywe config set organizationId <org>
koywe flow order           # Guiado: cotización → crear orden → esperar aprobación

init y setup abren el navegador para iniciar sesión en localhost y luego provisionan credenciales vía API — sin copiar secretos del dashboard. Usa setup si aún no tienes un comercio; usa init si ya lo tienes.

Autenticación

Tres opciones, elige una:

Login por navegador (humanos)

koywe auth browser-login

1. 1

   El CLI abre un listener local

   El CLI levanta un servidor HTTP efímero en 127.0.0.1:<puerto-aleatorio> y genera un nonce CSRF state.

2. 2

   El CLI abre el navegador

   Abre https://api.koywe.com/api/v1/cli-auth?callback=<loopback-url>&state=<nonce> en tu navegador.

3. 3

   La API valida y redirige

   GET /api/v1/cli-auth verifica que callback sea un URL http://127.0.0.1:<puerto>/... y redirige el navegador a la página /cli-auth del dashboard de Koywe, pasando callback y state.

4. 4

   El dashboard autoriza y devuelve

   Si ya has iniciado sesión, el dashboard publica un token de corta duración al callback loopback, devolviendo el state para que el CLI lo compare con el que generó.

5. 5

   El CLI cachea el token

   Si coinciden, el CLI escribe ~/.koywe/.cache/token.json y el listener HTTP se apaga. Ya estás autenticado.

API key + secret (CI, agentes, scripts)

koywe auth login --api-key TU_KEY --secret TU_SECRET
# apuntar a producción explícitamente:
koywe auth login --api-key TU_KEY --secret TU_SECRET --env production

Variables de entorno (CI / agentes sin configuración)

El token se cachea en ~/.koywe/.cache/token.json y se refresca automáticamente.

Grupos de comandos

Ver la referencia completa de comandos →

Descubrimiento por esquema para agentes

26 de los 142 comandos en CLI v0.14.1 aceptan --schema (busca el marcador 📐 en la referencia completa). Entre ellos:

koywe orders create --schema
koywe contacts create --schema
koywe bank-accounts create --schema
koywe policy rules create --schema

Nótese que no todo create acepta --schema — por ejemplo, auth credentials create y users invitations create no lo aceptan (tienen banderas propias). Ejecuta npx @koyweforest/cli --commands | jq '.data.commands[] | select(.hasSchema) | .name' para la lista autoritativa.

La salida incluye nombres de campo, tipos, flags de required, enums y descripciones por campo — es la misma forma que la API valida. Si el esquema contradice la spec OpenAPI, el esquema gana (y eso es un bug que vale la pena reportar).

Catálogo de comandos legible por máquina

koywe --commands

Emite el árbol completo de comandos como JSON, con el api.method y api.path subyacente de cada comando, sus opciones y si acepta --schema. Es el mismo JSON usado para generar la Referencia de Comandos CLI, y también se publica en /cli-commands.json.

Úsalo para traducir entre invocaciones del CLI y llamadas REST directas, o para auto-generar tooling alrededor del CLI.

Flujos guiados

flow encadena múltiples llamadas API en una sola invocación. Dos flujos hoy:

flow order — cotización + crear + esperar

# PAYIN: recibir CLP vía Khipu
npx @koyweforest/cli flow order \
  --type PAYIN \
  --origin CLP --destination CLP \
  --amount-in 100000 \
  --payment-method KHIPU
 
# PAYOUT: enviar CLP a una cuenta bancaria pre-registrada
npx @koyweforest/cli flow order \
  --type PAYOUT \
  --origin CLP --destination CLP \
  --amount-out 50000 \
  --destination-account-id bacc_...
 
# BALANCE_TRANSFER: convertir entre monedas dentro de un comercio
npx @koyweforest/cli flow order \
  --type BALANCE_TRANSFER \
  --origin CLP --destination USDC \
  --amount-in 50000 \
  --wait

Pasa --wait para hacer polling hasta que la orden salga de ON_HOLD (útil cuando una regla de policy la pone en aprobación). Pasa --mfa-token <token> para confirmar de inmediato.

flow deal — cripto ONRAMP/OFFRAMP de una vez

npx @koyweforest/cli flow deal \
  --type ONRAMP \
  --origin USD --destination USDC \
  --network ETHEREUM \
  --amount-in 100 \
  --transfer \
  --destination-address 0x...

Policy — requerida para BALANCE_TRANSFER y operaciones con MFA

Muchas operaciones mutadoras (BALANCE_TRANSFER, transferencias de fondos, cambios de config sensibles) requieren una policy activa con al menos una regla coincidente. Sin policy, la API devuelve POL00002 (deny por privilegio cero) o POL00007 (aprobación requerida).

Setup mínimo viable:

# Crear una policy a nivel de organización
npx @koyweforest/cli policy create --data '{"name":"default"}'
 
# Agregar una regla que permita órdenes BALANCE_TRANSFER
npx @koyweforest/cli policy rules create --schema   # ver el esquema exacto
npx @koyweforest/cli policy rules create --data '{
  "name": "allow-balance-transfer",
  "scope": "ORDER",
  "match": { "orderType": ["BALANCE_TRANSFER"] },
  "decision": { "action": "ALLOW" }
}'

Las operaciones bloqueadas por aprobaciones MFA_REQUIRED devuelven un ID de aprobación pendiente. Apruébalas vía koywe policy approvals approve <id> o con un --mfa-token pre-emitido.

Patrones de uso

Crear una orden desde JSON en línea

npx @koyweforest/cli orders create --data '{
  "type": "PAYIN",
  "originCurrencySymbol": "CLP",
  "destinationCurrencySymbol": "USDC",
  "amountIn": 100000,
  "paymentMethods": [{ "method": "KHIPU" }]
}'

Desde un archivo

npx @koyweforest/cli orders create --file order.json

Desde stdin (amigable con pipes)

cat order.json | npx @koyweforest/cli orders create

Listar con filtros

npx @koyweforest/cli orders list \
  --status COMPLETED --type PAYIN \
  --start-date 2025-01-01 \
  --format table

Formatos de salida

La salida JSON sigue un envelope consistente:

{
  "ok": true,
  "data": { ... },
  "meta": { "page": 1, "limit": 20, "total": 42 }
}

En caso de error, el proceso sale con código no-cero y escribe un envelope JSON de error en stderr:

{
  "ok": false,
  "error": { "code": "BAA00008", "message": "The destination account currency does not match the order destination currency." }
}

Ver Códigos de error para el catálogo completo.

Códigos de salida

Banderas globales

Gestión de perfiles

Cambia entre entornos sin re-autenticar:

koywe config profile add staging --env sandbox
koywe config profile add prod --env production
koywe config profile use staging
koywe config profile list