Referencia del CLI (en camino)

Los comandos, flags y formatos de salida previstos para el CLI, todavía no se puede instalar

El CLI está en camino: todavía no se puede usar

@notta/cli no está publicado en npm: npm i -g @notta/cli falla hoy, y el binario notta no se puede instalar por ningún medio. Esta página describe los comandos previstos, para que puedas planificar tu integración; ninguno de sus ejemplos es ejecutable todavía.

Los canales disponibles hoy son la API REST y el MCP, más el dashboard. Todos los ejemplos curl de estas docs funcionan ahora mismo con una API key.

El binario notta va a exponer los mismos recursos que la API REST desde tu terminal: misma API key, mismos shapes de respuesta.

Sin API key configurada, el CLI correrá en modo demo: avisará por stderr y los resultados no serán DTEs reales.

Grupos de comandos

Grupo	Para qué
`notta auth`	login / whoami / logout: manejo local del API key
`notta orgs`	listar tus organizaciones y fijar la org activa
`notta init`	wizard interactivo de onboarding SII hasta sandbox
`notta cert`	subir y administrar certificados digitales `.p12`
`notta caf`	subir CAFs y monitorear folios disponibles
`notta dte`	emitir, listar y descargar DTEs
`notta rcv`	Registro de Compras y Ventas desde el portal SII
`notta audit`	consultar y verificar el audit log (hash chain, 6 años)
`notta doctor`	diagnóstico del entorno y de la conectividad

Formato de salida

Los comandos de lectura aceptan --format table|json|csv. Sin el flag, el CLI detecta el contexto: tabla si la salida es una terminal interactiva, JSON si está piped (ideal para scripts). Los errores de la API se imprimen a stderr con code, hint y next_action: el catálogo completo está en Errores.

notta auth

Subcomando	Qué hace
`notta auth login`	pide el API key (`ntt_cert_...`, `ntt_prod_...` o legacy `rk_test_...`) y lo guarda en `~/.config/notta/credentials`
`notta auth whoami`	muestra el prefijo del key activo y su entorno (production / sandbox)
`notta auth logout`	borra el archivo de credenciales

notta auth login
# Paste your Notta API key (ntt_cert_..., ntt_prod_..., or legacy rk_test_.../rk_live_...):
# ✔ API key saved to ~/.config/notta/credentials

El CLI apunta a https://app.notta.cl por defecto. Puedes cambiar el destino con la variable de entorno NOTTA_API_URL.

notta dte

dte emit

Emisión simple de facturas tipo 33 y 34. El comando no tiene flag de referencias: las NC (61) y ND (56), que requieren references con cod_ref, se emiten vía la API de DTEs.

Flag	Requerido	Descripción
`--tipo`	sí	`33` (Factura afecta) o `34` (Factura exenta)
`--to`	sí	RUT del receptor en formato BODY-DV (p. ej. `11111111-1`)
`--name`	sí	razón social del receptor
`--giro`	sí	giro del receptor (no vacío): obligatorio para 33/34
`--direccion`	sí	dirección del receptor (no vacío): obligatorio para 33/34
`--comuna`	sí	comuna del receptor (no vacío): obligatorio para 33/34
`--forma-pago`	sí	forma de pago: `1` (Contado), `2` (Crédito) o `3` (Sin costo). Obligatorio para 33/34
`--item`	sí	spec `"nombre:cantidad:precio_unitario"`: repetible para múltiples ítems
`--env`	no	confirma el ambiente que esperas: `cert` (maullin.sii.cl) o `prod` (palena.sii.cl). No lo elige: el ambiente sale de tu API key. Si no calza con ella, el servidor rechaza la emisión sin emitir nada. Sin el flag, emite en el ambiente de la key
`--esperar [N]`	no	espera hasta `N` segundos (10 si no indicas un valor) a que el documento quede enviado al SII y lo muestra con su número de envío (`track_id`). Enviado no es aceptado: el veredicto llega después. Disponible en certificación y producción. Si la espera no alcanza, también es el `202`: el documento sigue en segundo plano. No lo emitas de nuevo: cada `notta dte emit` sin `--idempotency-key` manda otra `Idempotency-Key` y crearías un segundo documento, con otro folio. Consulta su estado con `notta dte show <id>`
`--pdf`	no	sólo junto a `--esperar` (sin él, el comando falla antes de emitir): guarda el PDF del documento en `<id>.pdf`, en la carpeta actual. Como `--esperar`, disponible en certificación y producción. Si la respuesta es el `202`, no trae PDF: no lo emitas de nuevo, consulta su estado con `notta dte show <id>`. Si el archivo no se puede escribir, el documento igual quedó emitido y enviado al SII
`--idempotency-key <valor>`	no	clave de idempotencia (header `Idempotency-Key`): texto no vacío, sin saltos de línea ni caracteres fuera de latin1. Sin el flag el CLI genera un UUID, lo imprime en stderr antes de enviar (así no se pierde si cortas con Ctrl-C) y lo repite en la salida como `idempotency_key` (JSON, tabla y CSV). Si el pedido falla sin respuesta (corte de red, timeout, cuerpo cortado a mitad de camino) o con un error 5xx (con o sin JSON), no sabes si el documento se emitió: el CLI termina con error y te indica el comando de reintento. Repite el comando con la misma `Idempotency-Key` y obtienes el documento que ya se emitió, en vez de un segundo documento con otro folio. Un error de validación (4xx con `code`) o un 4xx de un proxy que no es JSON no emitió nada: ahí puedes corregir y volver a correr. La excepción es el `409` `idempotency_conflict`: el documento ya existe (el CLI imprime su id y `notta dte show <id>`). Si es el que querías, ya está emitido; si querías otro distinto, usa una clave nueva. Lo aceptan también `dte emit-compra`, `dte emit-guia` y `dte emit-exportacion`. En `dte emit-guia` el cuerpo de la guía siempre lleva fecha; si no pasas `--fecha`, el CLI usa la de hoy, así que al reintentar repite la misma `--fecha` que indica el CLI y, con la misma clave y los mismos datos, el servidor devuelve la guía ya emitida aunque esa fecha ya sea pasada. Sin ella, pasada la medianoche la fecha cambia y la respuesta es `409`
`--format`	no	`table` \| `json` \| `csv`

notta dte emit \
  --tipo 33 \
  --to 11111111-1 \
  --name "Cliente Ejemplo SpA" \
  --giro "Comercio" \
  --direccion "Av Siempre Viva 123" \
  --comuna "Santiago" \
  --forma-pago 2 \
  --item "Consultoría mayo 2026:5:50000" \
  --item "Soporte mensual:1:120000" \
  --env cert

En el spec de --item, cantidad y precio_unitario admiten hasta 6 decimales (los mismos que acepta el SII), así que puedes escribir "Perno:4050:137.25". El monto_item que el CLI calcula sí queda entero: round(cantidad × precio), tal como lo exige el SII para el monto de cada línea. Para tipo 34 el CLI marca todos los ítems como exentos automáticamente, y el RUT emisor sale de tu org activa. El detalle del flujo completo está en Emitir Factura 33.

dte emit-guia

Emite una Guía de Despacho electrónica (DTE 52). Pide el despacho completo (transportista, conductor y vehículo) que dte emit no puede expresar. Como en las facturas, el SII exige el receptor completo: si falta --giro, --direccion o --comuna (o van en blanco), el comando termina con error antes de enviar nada y te dice cuáles faltan. Vale también en traslado interno (--traslado 5): por la API el servidor no completa el receptor por ti.

Flag	Requerido	Descripción
`--rut`	sí	RUT del emisor en formato BODY-DV
`--to`	sí	RUT del receptor en formato BODY-DV (p. ej. `11111111-1`)
`--name`	sí	razón social del receptor
`--giro`	sí	giro del receptor (no vacío, máx 40 caracteres)
`--direccion`	sí	dirección del receptor (no vacío, máx 70 caracteres)
`--comuna`	sí	comuna del receptor (no vacía, máx 20 caracteres)
`--item`	sí	spec `"nombre:cantidad:precio_unitario"` (o `...:exento`): repetible
`--traslado`	sí	`IndTraslado`: `1` venta, `2` ventas por efectuar, `3` consignaciones, `5` traslado interno, `6` otros traslados no venta, `7` devolución
`--tipo-despacho`	según `--traslado`	`1`, `2` o `3`. Obligatorio salvo en traslado interno (`--traslado 5`), donde no se pasa
`--origen-direccion`, `--origen-comuna`	sí	origen del traslado
`--destino-direccion`, `--destino-comuna`	sí	destino del traslado
`--transportista-rut`, `--transportista-nombre`	sí	datos del transportista
`--conductor-rut`, `--conductor-nombre`	sí	datos del conductor
`--patente`	sí	patente del vehículo
`--fecha`	no	fecha de la guía AAAA-MM-DD: por defecto hoy (zona Chile)
`--origen-ciudad`, `--destino-ciudad`	no	ciudad de origen y de destino
`--env`	no	confirma el ambiente que esperas (`cert` o `prod`); no lo elige
`--idempotency-key <valor>`	no	clave de idempotencia, igual que en `dte emit`
`--format`	no	`table` \| `json` \| `csv`

dte list

Flag	Descripción
`--tipo`	filtrar por tipo de DTE (p. ej. `33`)
`--folio`	filtrar por folio exacto: combínalo con `--tipo` para el documento exacto
`--rut-receptor`	filtrar por RUT del receptor (los puntos y la `k` minúscula dan lo mismo)
`--from`	fecha de emisión desde, `YYYY-MM-DD`
`--to`	fecha de emisión hasta, `YYYY-MM-DD`
`--limit`	filas por página, 1–100 (default 20)
`--cursor`	el cursor de la página anterior
`--format`	`table` \| `json` \| `csv`

Pagina con cursor: si hay más resultados, imprime More results available. Re-run with --cursor <cursor>, ver Paginación.

Para bajar el PDF de un documento que conoces por su folio, primero resuelve su id:

notta dte list --tipo 33 --folio 1042 --format json
notta dte pdf <id>

dte show / pdf / xml

Subcomando	Qué hace
`notta dte show <id>`	detalle completo del DTE, siempre en JSON
`notta dte pdf <id> [--output\|-o <archivo>]`	descarga el PDF (default `<id>.pdf`)
`notta dte xml <id> [--output\|-o <archivo>]`	descarga el XML firmado (default `<id>.xml`)

notta cert

Subcomando	Flags	Qué hace
`notta cert upload <archivo>`	`--password` (requerido), `--label`	carga tu `.p12` en el Vault de Notta
`notta cert list`	`--format`	lista los certificados de la org activa
`notta cert info <id>`	—	metadatos del certificado: nunca expone la clave privada
`notta cert rm <id>`	—	elimina un certificado

notta cert upload ./mi-cert.p12 --password ******** --label "Producción"

Es el mismo flujo que en el dashboard, ver Subir certificado.

notta caf

Subcomando	Flags	Qué hace
`notta caf upload <archivo>`	—	carga el XML del CAF que descargaste del portal SII
`notta caf list`	`--rut`, `--tipo`, `--format`	CAFs activos y rangos de folios disponibles
`notta caf status`	—	resumen por tipo de DTE, con alerta cuando queda menos del 10% de folios

notta caf list --tipo 33 --format json

Grupos menores

Comando	Qué hace
`notta init`	wizard interactivo: certificado → CAF → primer DTE en sandbox
`notta orgs list` / `notta orgs use <slug>`	ver tus orgs y fijar la activa para la sesión
`notta rcv list --rut <rut> --period <YYYY-MM> [--type received\|issued]`	entradas del RCV del período (compras o ventas)
`notta rcv refresh --rut <rut>`	dispara la sincronización del RCV desde el portal SII
`notta audit list [--action] [--from] [--to]`	entradas del audit log, filtrables por acción
`notta audit verify [--from] [--to]`	verifica la integridad del hash chain del audit log
`notta doctor`	chequea API key, Node ≥ 20 y permisos `600` del archivo de credenciales

notta rcv list --rut 76123456-0 --period 2026-04 --type received

Próximos pasos

Emitir Factura 33: la guía completa de emisión, con el shape entero del request y los estados SII.
Servidor MCP: el mismo catálogo como herramientas tipadas para tu agente LLM, con techo por empresa y aprobación humana sobre el umbral.
Errores: el catálogo de códigos con next_action que el CLI imprime en cada fallo.
RCV y F29: qué calcula Notta a partir del registro del SII.
Webhooks: el push de cambios de estado. Se registra por la API REST, no desde el CLI.

Referencia del CLI (en camino)

En esta página