@redcumbrecl/cli

El CLI de REDCUMBRE: conecta tu proyecto con la API en el modo de prueba, opera la API desde la terminal y pasa a real cuando estés listo.

npx @redcumbrecl/cli init

init inicia sesión con tu cuenta en el navegador, deja instalada una llave de prueba sin preguntar y termina con una primera prueba: emite una factura con el emisor de prueba y abre su PDF. En el modo de prueba nada llega al SII ni a nadie, y nada se cobra.

• La llave queda en keys/redcumbre-prueba.json (el mismo JSON que descarga la pantalla web de llaves) y el .env sólo apunta a ese archivo (REDCUMBRE_LLAVE_PRUEBA=keys/redcumbre-prueba.json). La llave real, cuando la agregues, queda en keys/redcumbre-real.json y REDCUMBRE_LLAVE_REAL. keys/, .redcumbre/ y .env (si no lo versionas ya) quedan fuera del control de versiones.
• En una carpeta vacía, init --lenguaje <typescript|python|dotnet|php> arma antes el proyecto con el generador del lenguaje y le agrega el AGENTS.md y la receta factura.
• Crear llaves exige ser administrador de la empresa. Si no tienes cuenta, redcumbre solicitar-cuenta.

Comandos

| Comando | Qué hace | |---|---| | init [--empresa <slug>] [--lenguaje …] [--entorno prueba\|real] | Conecta el proyecto con una llave de prueba y hace la primera prueba | | pasar-a-real [--servicios <códigos>] | Revisa que todo esté en orden y agrega la llave real (lo hace una persona) | | login [--json] [--codigo <código>] · logout | Inicia o cierra la sesión | | llaves · llaves revocar <id> --confirmar <slug> | Lista las llaves de la empresa y marca las del proyecto; revoca una | | llaves validafirma --empresa <slug> --alcance carpetas\|cuenta [--modo prueba\|real] | Crea la llave con la que el CLI de ValidaFirma trabaja en una empresa | | llamadas [--llave <id>] [--real] | Las últimas llamadas a la API hechas con la llave del proyecto | | webhooks escuchar --reenviar-a <url> [--eventos a,b] | Recibe en tu computador los webhooks de la empresa | | eventos · eventos disparar <evento> | Los eventos de webhook del modo de prueba, y dispara uno | | escenarios | Los emisores, RUT y simulaciones del modo de prueba | | bandeja | Los correos y mensajes que el modo de prueba retuvo en vez de enviarlos | | estado · restaurar --confirmar <slug> | El modo de cada llave y el tope diario; borra lo emitido en prueba y vuelve a sembrar | | api [<operación>] [--param k=v] [--cuerpo @archivo\|-] [--real] [--ensayo] | Ejecuta una operación de la API con la llave del proyecto | | api describir <operación> · api buscar <texto> | Describe una operación o busca entre ellas | | consumo [--real] | Lo consumido del plan y los topes del día | | receta <consultar-rut\|factura\|boleta-honorarios\|boleta-terceros> [--lenguaje …] | Agrega una receta que funciona en el modo de prueba (sólo agrega archivos) | | mcp agregar\|quitar [--asistente claude-code\|cursor] | Conecta o desconecta el servidor MCP de REDCUMBRE en tu asistente | | solicitar-cuenta | Pide una cuenta para tu empresa (lo hace una persona) | | doctor | Revisa la sesión, la empresa, las llaves, las exclusiones de git y el documento del API | | panel | Abre el panel de la empresa del proyecto en el navegador |

Para probar una operación sin escribir código, redcumbre api buscar <texto> la encuentra, redcumbre api describir <operación> muestra sus parámetros y redcumbre api <operación> la ejecuta con la llave de prueba del proyecto (--real para la real).

Toda operación que afecta datos reales pide confirmar escribiendo el slug de la empresa (--confirmar <slug>). Las que emiten llevan una clave de idempotencia: el CLI la imprime y la reusas con --clave si reintentas.

Para agentes de código

Con --json (o sin terminal) el CLI no pregunta nada: la salida estándar trae sólo JSON, los avisos van a la salida de errores y nunca incluye el secreto de una llave. Lo que necesita a una persona —iniciar sesión, crear la llave real, confirmar una operación real, solicitar una cuenta— sale con un código distinto de 0 y el comando que la persona tiene que correr en error.comando:

{ "error": { "codigo": "SIN_SESION", "mensaje": "…", "comando": "redcumbre login --json" } }

login --json entrega la URL para que la persona la abra y login --codigo <código> completa el inicio de sesión.

Llave de ValidaFirma

redcumbre llaves validafirma --empresa <slug> --alcance carpetas|cuenta [--modo prueba|real] [--json]

Crea en la empresa la llave con la que el CLI de ValidaFirma trabaja, y la deja en keys/validafirma-<empresa>-<alcance>-<modo>.json con permisos 0600. No habla con ValidaFirma, y no toca .env, .redcumbre/estado.json ni la llave del proyecto. La empresa tiene que tener ValidaFirma activo.

| Bandera | Valores | |---|---| | --empresa <slug> | Obligatoria. El identificador de la empresa (tenantSlug) | | --alcance <alcance> | Obligatoria. carpetas (carpetas y documentos) o cuenta (cuenta corporativa) | | --modo <modo> | prueba (por omisión) o real. La real la crea una persona en una terminal, escribiendo el slug | | --json | La salida estándar trae sólo el JSON de abajo |

Si el archivo ya existe y su llave sigue funcionando en esa empresa, con ese modo y ese rol, la reutiliza y no crea otra. Si no funciona, crea una nueva en su lugar.

{ "archivo": "keys/validafirma-agua-sur-carpetas-prueba.json", "empresa": { "slug": "agua-sur", "nombre": "Agua Sur" },
  "alcance": "carpetas", "modo": "prueba", "rol": "VALIDAFIRMA_API", "llaveId": "…", "resultado": "creada" }

| Clave | Qué trae | |---|---| | archivo | La ruta absoluta de la llave | | empresa | slug y nombre de la empresa | | alcance | carpetas o cuenta | | modo | prueba o real | | rol | El rol que la plataforma le dio a la llave | | llaveId | El id de la llave creada; null si se reutilizó | | resultado | creada, reutilizada o reemplazada |

Ningún campo trae el secreto de la llave. Cuando algo falla, el código de salida y error.codigo son:

| Caso | Salida | error.codigo | |---|---|---| | Sin sesión, sin terminal | 4 | SIN_SESION | | Tu cuenta no tiene permiso en la empresa | 6 | SIN_ROL | | La empresa no tiene ValidaFirma activo | 6 | VALIDAFIRMA_NO_ACTIVO | | Un alcance que el CLI no emite | 2 | ALCANCE_NO_EMITIDO | | Real sin terminal, o con terminal y otro texto que el slug | 3 | FALTA_CONFIRMACION | | La llave escrita no pasa la comprobación | 5 | LLAVE_RECHAZADA | | Falta una bandera obligatoria, --empresa vacía o un --modo que no existe | 2 | USO_INCORRECTO | | El archivo de la llave no se lee como una llave | 1 | ERROR_DEL_CLI | | La API no responde | 7 | SIN_CONEXION | | La API responde un error 5xx | 7 | API_NO_DISPONIBLE |

Las banderas, las claves de la salida y esta tabla son un contrato: no cambia sin una versión mayor del paquete.

Códigos de salida

| Código | Significa | |---|---| | 0 | Listo | | 1 | Error del CLI o del proyecto | | 2 | Uso incorrecto (comando, opción o valor que no existe) | | 3 | Falta la confirmación de una persona | | 4 | Falta iniciar sesión, o la sesión venció | | 5 | Falta la llave, o la API la rechaza | | 6 | La API respondió un error 4xx | | 7 | La API respondió un error 5xx o no respondió | | 8 | La llave es de otro modo (prueba en vez de real, o al revés) |

Sesión

redcumbre logout cierra la sesión y la revoca. La sesión se guarda en el llavero del sistema o, si no hay, en un archivo 0600 de tu carpeta de configuración — nunca en el proyecto. Con REDCUMBRE_SESION_EN_ARCHIVO=1 va al archivo aunque haya llavero (útil en contenedores y equipos compartidos).

Documentación: https://docs.redcumbre.cl/primeros-pasos/integrar-con-ia/