Metadata-Version: 2.4
Name: sii-cli
Version: 0.1.0
Summary: CLI + MCP server to automate SII Chile interactions
Keywords: sii,chile,tax,impuestos,dte,f29,rcv,cli,mcp
Author: Alberto Marturelo Lorenzo
Author-email: Alberto Marturelo Lorenzo <amarturelo@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Natural Language :: Spanish
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Typing :: Typed
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: playwright>=1.48
Requires-Dist: keyring>=25.0
Requires-Dist: typer>=0.12
Requires-Dist: pydantic>=2.7
Requires-Dist: httpx>=0.27
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/albertomarturelo/sii-cli
Project-URL: Repository, https://github.com/albertomarturelo/sii-cli
Project-URL: Issues, https://github.com/albertomarturelo/sii-cli/issues
Project-URL: Changelog, https://github.com/albertomarturelo/sii-cli/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# sii

Python CLI + MCP server to automate routine interactions with **SII Chile** (Servicio de Impuestos Internos) for a single user acting on their own RUT (or an empresa they legally represent).

- `sii` — the CLI (Typer-based)
- `sii-mcp` — the Model Context Protocol server (FastMCP, stdio)

The same `sii.core` engine backs both, so legal and operational guardrails (per-RUT throttling, audit log, credential handling, session lifecycle) apply regardless of which frontend a human or AI assistant uses.

## Status

**Production-targeted** — prod-only by default, no cert sandbox (ADR-016). Implemented end-to-end against the live SII portal:

- **`auth`** — interactive login + identity readback (`login` / `status [--refresh]` / `logout`).
- **`profile`** — full contribuyente snapshot (incl. PII).
- **`rcv`** — Registro de Compras y Ventas: `summary` (single period, `--year`, `--from/--to` range) + `list` (per-DTE rows) + `match` (reconcile a folio).
- **`f29`** — Declaración Mensual de IVA: `draft` (the pre-filled propuesta, read-only).

DTE (factura electrónica, SOAP) and further surfaces (BTE, carpeta tributaria, F22) are tracked in [`docs/ROADMAP.md`](docs/ROADMAP.md) and as GitHub issues.

## Install

Requires Python 3.12+ and [uv](https://github.com/astral-sh/uv).

```bash
uv sync
uv run playwright install chromium
```

## Quickstart

Authentication is **interactive** (ADR-018/019) — the Clave Tributaria is prompted, never passed on the command line or stored in shell history.

```bash
# Log in once — prompts for RUT + Clave Tributaria, persists to the OS keyring
uv run sii auth login

# Session + identity
uv run sii auth status              # pure local read of the cached session
uv run sii auth status --refresh    # hits SII, reads identity from Mi Sii
uv run sii profile                  # full contribuyente snapshot (PII; use status -r for the safe subset)

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

# F29 (IVA mensual) — read SII's pre-filled propuesta (read-only, never submits)
uv run sii f29 draft --period 2026-05

# Operate on an empresa you legally represent (ADR-015)
uv run sii f29 draft --period 2026-05 --rut 11111111-1

# Sanity check: resolved hostnames + rate limit
uv run sii status

# Close the session cleanly when done (avoids the stale-session block, ADR-011)
uv run sii auth logout
```

Most commands take `--format json` (default, pipe to `jq`) or `--format table`.

The MCP server runs over stdio (default for Claude Desktop / Claude Code) and exposes the same operations (`auth_status`, `profile`, `rcv_summary`, `rcv_list`, `rcv_match`, `f29_draft`, `current_config`):

```bash
uv run sii-mcp
# Or with the MCP Inspector for debugging:
uv run mcp dev src/sii/mcp/server.py
```

## Methodology

This repository follows **Context-First Development** (CFD): every architectural and process decision lives as an ADR under `docs/decisions/`, work units are tracked as GitHub issues with a fixed body template, and PR review cross-checks the diff against the indices rather than scanning full files.

- `CLAUDE.md` — root index (≤100 lines).
- `docs/ARCHITECTURE.md`, `STACK.md`, `CONVENTIONS.md`, `CURRENT_STATUS.md`, `ROADMAP.md` — loaded on demand.
- `docs/decisions/` — 20 ADRs covering the three-layer split, single-env (prod), the in-house SII contract, session lifecycle, rate limits, multi-RUT, interactive auth, the GitHub workflow, review philosophy, and the SII wire-contract docs convention.
- `docs/sii-contract/` — the observed SII wire contracts per surface (endpoints, payloads, enum legends, captcha posture), one doc per surface following a canonical template (ADR-020).
- `.claude/commands/` — slash commands (`issue-new`, `issue-start`, `review-pr`, `session-start`, `session-close`, etc.).
- `.github/` — PR + issue templates aligned with the ADRs.

CFD itself: <https://github.com/albertomarturelo/context-first-development>.

## Posture

This project automates a user's interaction with **their own** SII account (or accounts they legally represent). It does not target multi-tenant SaaS use; it does not rotate IPs to evade rate limits; it stores no shared credentials; it logs every operation locally. See `docs/decisions/003-tos-posture-own-account-only.md`.

**Disclaimer.** This is an independent, community tool — **not affiliated with, authorised by, or endorsed by SII (Servicio de Impuestos Internos)**. It drives the public taxpayer portal by observing its behaviour (no official non-DTE API exists); SII can change the portal at any time and break it without notice. Provided **as is, without warranty** (see [LICENSE](LICENSE)). You are responsible for your use of it and for complying with SII's terms.

## License

[Apache-2.0](LICENSE) © Alberto Marturelo Lorenzo.
