sii-cli 0.2.0

CLI + MCP server to automate SII Chile interactions

sii

CLI + servidor MCP para automatizar interacciones rutinarias con el SII de Chile (Servicio de Impuestos Internos), para un único usuario que actúa sobre su propio RUT (o una empresa que representa legalmente).

• sii — la CLI (basada en Typer)
• sii-mcp — el servidor Model Context Protocol (FastMCP, stdio)

El mismo motor sii.core respalda ambos frontends, así que las salvaguardas legales y operativas (throttling por RUT, log de auditoría, manejo de credenciales, ciclo de vida de la sesión) aplican sin importar si quien lo usa es una persona o un asistente de IA.

Estado

Orientado a producción — solo prod por defecto, sin sandbox de certificación (ADR-016). Implementado de punta a punta contra el portal real del SII:

• auth — login interactivo + lectura de identidad (login / status [--refresh] / logout).
• profile — snapshot completo del contribuyente (incluye PII).
• rcv — Registro de Compras y Ventas: summary (un período, --year, o rango --from/--to) + list (filas por DTE) + match (reconciliar un folio).
• f29 — Declaración Mensual de IVA: draft (la propuesta pre-llenada, solo lectura).

DTE (factura electrónica, SOAP) y otras superficies (BTE, carpeta tributaria, F22) están en el docs/ROADMAP.md y como issues de GitHub.

Instalación

Requiere Python 3.12+. Se instala directo desde PyPI, sin clonar el código:

# Como herramienta aislada (recomendado) — con uv o pipx:
uv tool install sii-cli
pipx install sii-cli

# O en tu entorno/venv actual con pip:
pip install sii-cli

Luego instala una sola vez el navegador headless que usa el portal (~150 MB):

uvx --from sii-cli playwright install chromium
# (si instalaste con pip dentro de un venv, basta:  playwright install chromium)

Esto deja los comandos sii y sii-mcp disponibles en tu PATH.

¿Solo quieres probarla sin instalar nada? Ejecútala efímera con uv:

uvx --from sii-cli sii status

Desde el código (desarrollo)

git clone https://github.com/albertomarturelo/sii-cli
cd sii-cli
uv sync
uv run playwright install chromium
# ejecuta con:  uv run sii ...

Uso rápido

La autenticación es interactiva (ADR-018/019): la Clave Tributaria se pide por pantalla, nunca se pasa por la línea de comandos ni queda en el historial del shell.

# Inicia sesión una vez — pide RUT + Clave Tributaria, la guarda en el keyring del SO
sii auth login

# Sesión + identidad
sii auth status              # lectura local de la sesión cacheada
sii auth status --refresh    # consulta al SII, lee la identidad desde Mi Sii
sii profile                  # snapshot completo del contribuyente (PII; usa status -r para el subconjunto seguro)

# Registro de Compras y Ventas (COMPRA = recibidas, VENTA = emitidas)
sii rcv summary --period 2026-05 --side COMPRA
sii rcv summary --year 2026 --side VENTA
sii rcv list --period 2026-05 --type compras --doc-type-code 33
sii rcv match --folio 12345

# F29 (IVA mensual) — lee la propuesta pre-llenada del SII (solo lectura, nunca envía)
sii f29 draft --period 2026-05

# Operar sobre una empresa que representas legalmente (ADR-015)
sii f29 draft --period 2026-05 --rut 11111111-1

# Chequeo rápido: hostnames resueltos + rate limit
sii status

# Cierra la sesión limpiamente al terminar (evita el bloqueo por sesión vieja, ADR-011)
sii auth logout

La mayoría de los comandos aceptan --format json (por defecto, para canalizar a jq) o --format table.

El servidor MCP corre sobre stdio (por defecto para Claude Desktop / Claude Code) y expone las mismas operaciones (auth_status, profile, rcv_summary, rcv_list, rcv_match, f29_draft, current_config):

sii-mcp

(Para depurar desde el código con el MCP Inspector: uv run mcp dev src/sii/mcp/server.py.)

Metodología

Este repositorio sigue Context-First Development (CFD): cada decisión de arquitectura o proceso vive como un ADR en docs/decisions/, las unidades de trabajo se registran como issues de GitHub con una plantilla de cuerpo fija, y la revisión de PRs contrasta el diff contra los índices en vez de leer archivos completos.

• CLAUDE.md — índice raíz (≤100 líneas).
• docs/ARCHITECTURE.md, STACK.md, CONVENTIONS.md, CURRENT_STATUS.md, ROADMAP.md — se cargan bajo demanda.
• docs/decisions/ — 22 ADRs (split de tres capas, single-env prod, el contrato SII in-house, ciclo de sesión, rate limits, multi-RUT, auth interactivo, el flujo de GitHub, filosofía de review, los docs de contrato SII, y la publicación open source).
• docs/sii-contract/ — los contratos de cable del SII observados por superficie (endpoints, payloads, leyendas de enums, postura de captcha), un doc por superficie siguiendo una plantilla canónica (ADR-020).
• .claude/commands/ — slash commands (issue-new, issue-start, review-pr, session-start, session-close, etc.).
• .github/ — plantillas de PR + issues alineadas con los ADRs.

CFD en sí: https://github.com/albertomarturelo/context-first-development.

Postura

Este proyecto automatiza la interacción de un usuario con su propia cuenta del SII (o cuentas que representa legalmente). No apunta a uso SaaS multi-tenant; no rota IPs para evadir rate limits; no guarda credenciales compartidas; registra cada operación localmente. Ver docs/decisions/003-tos-posture-own-account-only.md.

Aviso legal. Esta es una herramienta independiente y comunitaria — no está afiliada, autorizada ni avalada por el SII (Servicio de Impuestos Internos). Maneja el portal público del contribuyente observando su comportamiento (no existe una API oficial fuera de DTE); el SII puede cambiar el portal en cualquier momento y romperla sin aviso. Se entrega tal cual, sin garantía (ver LICENSE). Eres responsable de su uso y de cumplir los términos del SII.

Licencia

Apache-2.0 © Alberto Marturelo Lorenzo.