sii-cli 0.1.0__py3-none-any.whl

sii/cli/main.py

@@ -0,0 +1,925 @@
+import asyncio
+import json
+import logging
+from dataclasses import asdict
+from enum import Enum
+from pathlib import Path
+
+import typer
+
+from sii import __version__
+from sii.core import get_settings
+from sii.core.auth.portal_session import (
+    LoginFailedError,
+    NotAuthenticatedError,
+    RateLimitError,
+)
+from sii.core.config import DTE_WS, LOGIN_URL, PORTAL
+from sii.core.storage.credentials import CredentialNotFoundError
+from sii.core.tasks import (
+    AuthStatusRefresh,
+    DatosContribuyente,
+    F29Propuesta,
+    RcvDetalle,
+    RcvMatchResult,
+    RcvResumen,
+    RcvResumenRange,
+    RcvSide,
+    auth_login as _auth_login,
+    auth_logout as _auth_logout,
+    auth_status as _auth_status,
+    auth_status_refresh as _auth_status_refresh,
+    consultar_datos_contribuyente,
+    consultar_f29_propuesta,
+    consultar_rcv_detalle,
+    consultar_rcv_match,
+    consultar_rcv_resumen,
+    consultar_rcv_resumen_range,
+    consultar_rcv_resumen_year,
+    local_session_state as _local_session_state,
+    redact,
+)
+
+app = typer.Typer(
+    name="sii",
+    help="CLI para automatizar interacciones con el SII Chile.",
+    no_args_is_help=True,
+)
+
+rcv_app = typer.Typer(
+    name="rcv",
+    help="Registro de Compras y Ventas — listado de facturas y boletas por período.",
+    no_args_is_help=True,
+)
+app.add_typer(rcv_app, name="rcv")
+
+f29_app = typer.Typer(
+    name="f29",
+    help="Declaración Mensual de IVA (F29) — read SII's pre-filled propuesta.",
+    no_args_is_help=True,
+)
+app.add_typer(f29_app, name="f29")
+
+auth_app = typer.Typer(
+    name="auth",
+    help="Authentication — explicit verbs (status / login / logout). Decoupled "
+    "from domain tasks so a long-lived MCP server can warm up its session "
+    "deliberately.",
+    no_args_is_help=True,
+)
+app.add_typer(auth_app, name="auth")
+
+
+class _OutputFormat(str, Enum):
+    json = "json"
+    table = "table"
+
+
+@app.command()
+def status() -> None:
+    """Show the resolved hostnames and rate limit (sanity check)."""
+    s = get_settings()
+    typer.echo(f"dte_ws:      {DTE_WS}")
+    typer.echo(f"portal:      {PORTAL}")
+    typer.echo(f"login:       {LOGIN_URL}")
+    typer.echo(f"rate_limit:  {s.rate_limit_rps} req/s per RUT")
+
+
+@app.command()
+def version() -> None:
+    """Print the installed sii package version."""
+    typer.echo(__version__)
+
+
+def _print_datos_json(d: DatosContribuyente) -> None:
+    typer.echo(json.dumps(asdict(d), indent=2, ensure_ascii=False))
+
+
+def _print_datos_table(d: DatosContribuyente) -> None:
+    """Curated subset for humans: identidad + clasificación + actividad +
+    contacto + dirección principal. Use --format json for the full snapshot."""
+    typer.echo(f"rut:                       {d.rut}")
+    c = d.contribuyente
+    if c is not None:
+        nombre = (
+            c.razon_social
+            or " ".join(p for p in (c.nombres, c.apellido_paterno, c.apellido_materno) if p)
+            or None
+        )
+        if nombre:
+            typer.echo(f"nombre:                    {nombre}")
+        if c.tipo_contribuyente_descripcion:
+            typer.echo(f"tipo contribuyente:        {c.tipo_contribuyente_descripcion}")
+        if c.segmento_descripcion:
+            typer.echo(f"segmento:                  {c.segmento_descripcion}")
+        if c.glosa_actividad:
+            typer.echo(f"glosa actividad:           {c.glosa_actividad}")
+        if c.fecha_inicio_actividades:
+            typer.echo(f"fecha inicio actividades:  {c.fecha_inicio_actividades}")
+        if c.fecha_nacimiento:
+            typer.echo(f"fecha nacimiento:          {c.fecha_nacimiento}")
+        if c.email:
+            typer.echo(f"email:                     {c.email}")
+        if c.telefono_movil:
+            typer.echo(f"teléfono móvil:            {c.telefono_movil}")
+        if c.unidad_operativa_descripcion:
+            typer.echo(f"unidad operativa SII:      {c.unidad_operativa_descripcion}")
+        if c.unidad_operativa_direccion:
+            typer.echo(f"unidad operativa dir.:     {c.unidad_operativa_direccion}")
+    if d.direcciones:
+        principal = d.direcciones[0]
+        if principal.calle:
+            comuna = principal.comuna_descripcion or ""
+            sep = ", " if comuna else ""
+            typer.echo(f"dirección principal:       {principal.calle}{sep}{comuna}")
+    if d.atributos:
+        typer.echo(f"atributos:                 {len(d.atributos)}")
+        for a in d.atributos:
+            tag = a.atr_codigo or "?"
+            desc = a.desc_atr_codigo or ""
+            typer.echo(f"  - {tag}: {desc}")
+    typer.echo(f"fuente:                    {d.portal_url}")
+
+
+@app.command()
+def profile(
+    fmt: _OutputFormat = typer.Option(
+        _OutputFormat.json,
+        "--format",
+        "-f",
+        case_sensitive=False,
+        help="Output format. JSON (default) for machine consumption / piping to jq; "
+        "table for a curated human readout.",
+    ),
+    redact_pii: bool = typer.Option(
+        False,
+        "--redact",
+        help="Mask email, phone, address, DoB, and unidad-operativa address. RUT is NOT redacted.",
+    ),
+    dump_html: Path | None = typer.Option(
+        None,
+        "--dump-html",
+        help="Write the full authenticated-landing HTML to this path "
+        "(WARNING: contains real PII — never commit or share).",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+) -> None:
+    """Authenticate and return the FULL DatosCntrNow contribuyente snapshot.
+
+    Includes PII (email, phone, address, DoB). Use `sii auth status
+    --refresh` for the safe subset. Pass `--redact` to mask the
+    sensitive fields.
+    """
+    if verbose:
+        logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    try:
+        d = asyncio.run(consultar_datos_contribuyente(dump_html_to=dump_html))
+    except (CredentialNotFoundError, NotAuthenticatedError) as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+    except LoginFailedError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=3)
+    except RateLimitError as exc:
+        typer.secho(str(exc), fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(code=4)
+    if redact_pii:
+        d = redact(d)
+    if fmt is _OutputFormat.json:
+        _print_datos_json(d)
+    else:
+        _print_datos_table(d)
+    if dump_html is not None:
+        typer.echo(f"html:                      {dump_html}", err=True)
+
+
+def _print_refresh_table(r: AuthStatusRefresh) -> None:
+    """Curated human view of the identity snapshot. Mirrors the field
+    order the previous `sii whoami` table used so muscle memory survives
+    the surface rename (ADR-018)."""
+    typer.echo(f"rut:                       {r.rut}")
+    if r.nombre:
+        typer.echo(f"nombre:                    {r.nombre}")
+    if r.tipo_contribuyente:
+        typer.echo(f"tipo contribuyente:        {r.tipo_contribuyente}")
+    if r.segmento:
+        typer.echo(f"segmento:                  {r.segmento}")
+    if r.glosa_actividad:
+        typer.echo(f"glosa actividad:           {r.glosa_actividad}")
+    if r.fecha_inicio_actividades:
+        typer.echo(f"fecha inicio actividades:  {r.fecha_inicio_actividades}")
+    if r.unidad_operativa:
+        typer.echo(f"unidad operativa SII:      {r.unidad_operativa}")
+    typer.echo(f"fuente:                    {r.portal_url}")
+
+
+@auth_app.command(name="status")
+def auth_status_cmd(
+    refresh: bool = typer.Option(
+        False,
+        "--refresh",
+        "-r",
+        help="Hit the portal and read the live identity snapshot from "
+        "DatosCntrNow (RUT + nombre + tipo + segmento + glosa actividad + "
+        "fecha inicio actividades + unidad operativa). Requires an active "
+        "session — raises an error if not logged in (no implicit login).",
+    ),
+    fmt: _OutputFormat = typer.Option(
+        _OutputFormat.json,
+        "--format",
+        "-f",
+        case_sensitive=False,
+        help="Output format. JSON (default) for machine consumption; table for a human readout.",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+) -> None:
+    """Report session state. Local cache by default; `--refresh` hits SII.
+
+    Without `--refresh`: pure local read of `~/.sii/session.json` +
+    `~/.sii/session.meta`. Output: `authenticated`, `rut`,
+    `session_source`. No network call.
+
+    With `--refresh`: launches Playwright, reads the authenticated Mi
+    Sii landing, parses `DatosCntrNow`, and returns the curated
+    identity surface. Replaces the deleted `sii whoami` per ADR-018.
+    """
+    if verbose:
+        logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    if refresh:
+        try:
+            r = asyncio.run(_auth_status_refresh())
+        except (CredentialNotFoundError, NotAuthenticatedError) as exc:
+            typer.secho(str(exc), fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=2)
+        except LoginFailedError as exc:
+            typer.secho(str(exc), fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=3)
+        except RateLimitError as exc:
+            typer.secho(str(exc), fg=typer.colors.YELLOW, err=True)
+            raise typer.Exit(code=4)
+        if fmt is _OutputFormat.json:
+            typer.echo(json.dumps(asdict(r), indent=2, ensure_ascii=False))
+        else:
+            _print_refresh_table(r)
+        return
+    s = asyncio.run(_auth_status())
+    if fmt is _OutputFormat.json:
+        typer.echo(json.dumps(asdict(s), indent=2, ensure_ascii=False))
+    else:
+        typer.echo(f"authenticated:   {str(s.authenticated).lower()}")
+        typer.echo(f"rut:             {s.rut or '-'}")
+        typer.echo(f"session_source:  {s.session_source}")
+
+
+@auth_app.command(name="login")
+def auth_login_cmd(
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Wipe any existing session + keyring entry first, then start a "
+        "fresh interactive login. Use when you want to switch accounts or "
+        "reset a stuck state.",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+) -> None:
+    """Interactively authenticate against SII. See ADR-018.
+
+    No flags: prompts for RUT + Clave Tributaria, submits to SII,
+    persists the credential to OS keyring, and writes a session cache.
+    If a valid session is already active and `--force` is NOT set, the
+    command is idempotent: prints "already authenticated as <rut>" and
+    exits without prompting OR submitting.
+
+    Single-account: any prior credential is replaced. To switch
+    accounts, run `sii auth logout` then `sii auth login` again — or
+    just `sii auth login --force` which combines both.
+
+    The password is read via `getpass`-style hidden input — never on
+    the command line as a flag, never echoed to the terminal, never
+    recorded in shell history.
+    """
+    if verbose:
+        logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+
+    # Decide whether we need to prompt. `--force` always prompts.
+    # Otherwise, a pure local-cache read tells us if the task layer's
+    # idempotent fast-path can take over (no submit, no prompt) —
+    # using `local_session_state()` instead of `auth_status()` so the
+    # probe doesn't write a forensic audit entry every invocation.
+    need_prompt = force
+    if not force:
+        try:
+            authenticated, _ = _local_session_state()
+            if not authenticated:
+                need_prompt = True
+        except Exception:
+            need_prompt = True
+
+    rut_arg: str | None = None
+    password_arg: str | None = None
+    if need_prompt:
+        # Method prompt deferred: only RUT + Clave Tributaria is wired.
+        # The .pfx certificate path lands when DTE work starts (per
+        # ADR-018 Decision section).
+        typer.echo("Method: (1) RUT + Clave Tributaria")
+        rut_arg = typer.prompt("RUT").strip()
+        password_arg = typer.prompt("Clave Tributaria", hide_input=True)
+
+    try:
+        r = asyncio.run(_auth_login(rut=rut_arg, password=password_arg, force=force))
+    except (CredentialNotFoundError, NotAuthenticatedError) as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+    except LoginFailedError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=3)
+    except RateLimitError as exc:
+        typer.secho(str(exc), fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(code=4)
+
+    if r.reason == "already_authenticated":
+        typer.echo(f"already authenticated as {r.rut}")
+    elif r.reason == "forced":
+        typer.echo(f"forced re-login complete; authenticated as {r.rut}")
+    else:
+        typer.echo(f"authenticated as {r.rut}; credential saved to keyring")
+
+
+@auth_app.command(name="logout")
+def auth_logout_cmd(verbose: bool = typer.Option(False, "--verbose", "-v")) -> None:
+    """Close the active SII session (clears local + best-effort server-side close).
+
+    Per ADR-011, keeps stale-session accumulation under SII's ~1-hour
+    block threshold. Replaces the previous flat `sii logout` command.
+    """
+    if verbose:
+        logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    had_session = asyncio.run(_auth_logout())
+    if had_session:
+        typer.echo("sesión cerrada (local).")
+    else:
+        typer.echo("no había sesión activa.")
+
+
+def _print_rcv_resumen_json(r: RcvResumen) -> None:
+    typer.echo(json.dumps(asdict(r), indent=2, ensure_ascii=False))
+
+
+def _print_rcv_resumen_table(r: RcvResumen) -> None:
+    """Curated human view: header, per-DTE-type rows, totals at the bottom."""
+    typer.echo(f"rut:     {r.rut}")
+    typer.echo(f"period:  {r.period}")
+    typer.echo(f"side:    {r.side}")
+    typer.echo("")
+    if not r.rows:
+        typer.echo("(no rows for this period)")
+        if r.totals is None:
+            return
+    else:
+        typer.echo(
+            f"{'cod':<5}  {'descripción':<40}  {'docs':>6}  "
+            f"{'exento':>12}  {'neto':>12}  {'iva':>12}  {'total':>12}"
+        )
+        typer.echo("-" * 110)
+        for row in r.rows:
+            typer.echo(
+                f"{row.codigo_tipo_doc or '-':<5}  "
+                f"{(row.descripcion or '-')[:40]:<40}  "
+                f"{row.total_documentos if row.total_documentos is not None else '-':>6}  "
+                f"{row.monto_exento if row.monto_exento is not None else '-':>12}  "
+                f"{row.monto_neto if row.monto_neto is not None else '-':>12}  "
+                f"{row.monto_iva if row.monto_iva is not None else '-':>12}  "
+                f"{row.monto_total if row.monto_total is not None else '-':>12}"
+            )
+    if r.totals is not None:
+        t = r.totals
+        typer.echo("-" * 110)
+        typer.echo(
+            f"{'TOT':<5}  {'':<40}  "
+            f"{t.total_documentos if t.total_documentos is not None else '-':>6}  "
+            f"{t.monto_exento if t.monto_exento is not None else '-':>12}  "
+            f"{t.monto_neto if t.monto_neto is not None else '-':>12}  "
+            f"{t.monto_iva if t.monto_iva is not None else '-':>12}  "
+            f"{t.monto_total if t.monto_total is not None else '-':>12}"
+        )
+
+
+def _print_rcv_resumen_range_json(r: RcvResumenRange) -> None:
+    typer.echo(json.dumps(asdict(r), indent=2, ensure_ascii=False))
+
+
+def _print_rcv_resumen_range_table(r: RcvResumenRange) -> None:
+    """Curated human view: aggregated rows at top, per-month breakdown
+    footer. Mirrors `_print_rcv_resumen_table` formatting for visual
+    consistency."""
+    typer.echo(f"rut:            {r.rut}")
+    typer.echo(f"start period:   {r.start_period}")
+    typer.echo(f"end period:     {r.end_period}")
+    typer.echo(f"side:           {r.side}")
+    typer.echo(f"months:         {len(r.months)}")
+    typer.echo("")
+    typer.echo("=== AGGREGATED (sum across all months) ===")
+    if not r.aggregated:
+        typer.echo("(no rows for any period in this range)")
+    else:
+        typer.echo(
+            f"{'cod':<5}  {'descripción':<40}  {'docs':>6}  "
+            f"{'exento':>12}  {'neto':>12}  {'iva':>12}  {'total':>12}"
+        )
+        typer.echo("-" * 110)
+        for row in r.aggregated:
+            typer.echo(
+                f"{row.codigo_tipo_doc or '-':<5}  "
+                f"{(row.descripcion or '-')[:40]:<40}  "
+                f"{row.total_documentos if row.total_documentos is not None else '-':>6}  "
+                f"{row.monto_exento if row.monto_exento is not None else '-':>12}  "
+                f"{row.monto_neto if row.monto_neto is not None else '-':>12}  "
+                f"{row.monto_iva if row.monto_iva is not None else '-':>12}  "
+                f"{row.monto_total if row.monto_total is not None else '-':>12}"
+            )
+    typer.echo("")
+    typer.echo("=== PER-MONTH BREAKDOWN ===")
+    typer.echo(f"{'period':<8}  {'cods':>4}  {'docs':>6}  {'total':>14}")
+    typer.echo("-" * 40)
+    for m in r.months:
+        if not m.rows:
+            typer.echo(f"{m.period:<8}  {'-':>4}  {'-':>6}  {'(empty)':>14}")
+            continue
+        docs = sum(row.total_documentos or 0 for row in m.rows)
+        total = sum(row.monto_total or 0 for row in m.rows)
+        typer.echo(f"{m.period:<8}  {len(m.rows):>4}  {docs:>6}  {total:>14}")
+
+
+@rcv_app.command()
+def summary(
+    period: str | None = typer.Option(
+        None, "--period", help="Single tax period in YYYY-MM (e.g. 2026-06)."
+    ),
+    year: int | None = typer.Option(
+        None,
+        "--year",
+        help="Year to query as a single range (YYYY-01 .. YYYY-12). Mutually "
+        "exclusive with --period and --from/--to.",
+    ),
+    range_from: str | None = typer.Option(
+        None,
+        "--from",
+        help="Range start (inclusive) in YYYY-MM. Requires --to. Mutually "
+        "exclusive with --period and --year.",
+    ),
+    range_to: str | None = typer.Option(
+        None,
+        "--to",
+        help="Range end (inclusive) in YYYY-MM. Requires --from.",
+    ),
+    side: RcvSide = typer.Option(
+        ...,
+        "--side",
+        case_sensitive=False,
+        help="COMPRA (DTEs you received) or VENTA (DTEs you issued).",
+    ),
+    rut: str | None = typer.Option(
+        None,
+        "--rut",
+        help="Operating RUT (e.g. 12345670-K). Defaults to the authenticated "
+        "RUT; see ADR-015 for the multi-RUT model.",
+    ),
+    fmt: _OutputFormat = typer.Option(
+        _OutputFormat.json,
+        "--format",
+        "-f",
+        case_sensitive=False,
+        help="Output format. JSON (default) for machine consumption / piping to jq; "
+        "table for a curated human readout.",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+) -> None:
+    """Per-DTE-type summary of the RCV. Three mutually-exclusive modes.
+
+    `--period YYYY-MM`        — single period (original behavior).
+    `--year YYYY`             — January through December of the year.
+    `--from YYYY-MM --to YYYY-MM` — inclusive arbitrary range.
+
+    Multi-period modes loop ONE `logged_in_page()` across N months
+    (ADR-009) and pace consecutive POSTs via `asyncio.sleep(1.0 /
+    settings.rate_limit_rps)` (ADR-011). Per-month failures are isolated
+    — month K raising does NOT abort the rest; the failed month surfaces
+    with empty rows and the summary entry records `result="partial"`.
+    """
+    if verbose:
+        logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+
+    # Mutex: exactly one of {period, year, (range_from + range_to)}.
+    # `--from` and `--to` must come together to make sense.
+    has_period = period is not None
+    has_year = year is not None
+    has_from = range_from is not None
+    has_to = range_to is not None
+    if has_from ^ has_to:
+        typer.secho(
+            "invalid arguments: --from and --to must be supplied together.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+    has_range = has_from and has_to
+    modes = sum([has_period, has_year, has_range])
+    if modes == 0:
+        typer.secho(
+            "invalid arguments: one of --period, --year, or --from/--to is required.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+    if modes > 1:
+        typer.secho(
+            "invalid arguments: --period, --year, and --from/--to are mutually exclusive — pick one.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    try:
+        if has_period:
+            assert period is not None  # mypy
+            r: RcvResumen | RcvResumenRange = asyncio.run(
+                consultar_rcv_resumen(period=period, side=side, rut_operativo=rut)
+            )
+        elif has_year:
+            assert year is not None  # mypy
+            r = asyncio.run(consultar_rcv_resumen_year(year, side=side, rut_operativo=rut))
+        else:
+            assert range_from is not None and range_to is not None  # mypy
+            r = asyncio.run(
+                consultar_rcv_resumen_range(
+                    start_period=range_from,
+                    end_period=range_to,
+                    side=side,
+                    rut_operativo=rut,
+                )
+            )
+    except (CredentialNotFoundError, NotAuthenticatedError) as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+    except LoginFailedError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=3)
+    except RateLimitError as exc:
+        typer.secho(str(exc), fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(code=4)
+    except ValueError as exc:
+        typer.secho(f"invalid argument: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+
+    if isinstance(r, RcvResumenRange):
+        if fmt is _OutputFormat.json:
+            _print_rcv_resumen_range_json(r)
+        else:
+            _print_rcv_resumen_range_table(r)
+    else:
+        if fmt is _OutputFormat.json:
+            _print_rcv_resumen_json(r)
+        else:
+            _print_rcv_resumen_table(r)
+
+
+def _print_rcv_detalle_json(d: RcvDetalle) -> None:
+    typer.echo(json.dumps(asdict(d), indent=2, ensure_ascii=False))
+
+
+def _print_rcv_detalle_table(d: RcvDetalle) -> None:
+    """Curated human view: header + one row per DTE. Tax-special fields
+    (activo fijo, IVA uso común, Ley 18211, etc.) only show in `--format
+    json` via the `raw` payload."""
+    typer.echo(f"rut:               {d.rut}")
+    typer.echo(f"period:            {d.period}")
+    typer.echo(f"side:              {d.side}")
+    typer.echo(f"código tipo doc:   {d.codigo_tipo_doc}")
+    typer.echo("")
+    if not d.docs:
+        typer.echo("(no documents for this period/tipo)")
+        return
+    typer.echo(
+        f"{'folio':>10}  {'fecha':<10}  {'rut':<14}  "
+        f"{'razón social':<40}  {'neto':>12}  {'iva':>12}  {'total':>12}"
+    )
+    typer.echo("-" * 122)
+    for row in d.docs:
+        typer.echo(
+            f"{row.folio if row.folio is not None else '-':>10}  "
+            f"{(row.fecha_emision or '-'):<10}  "
+            f"{(row.rut_emisor or '-'):<14}  "
+            f"{(row.razon_social or '-')[:40]:<40}  "
+            f"{row.monto_neto if row.monto_neto is not None else '-':>12}  "
+            f"{row.monto_iva if row.monto_iva is not None else '-':>12}  "
+            f"{row.monto_total if row.monto_total is not None else '-':>12}"
+        )
+
+
+def _parse_rcv_type(value: str) -> RcvSide:
+    """Map the user-facing `--type` spelling to the internal RcvSide enum.
+
+    The contador-grade surface uses `compras` / `ventas` (ADR-017); the
+    older `COMPRA` / `VENTA` spelling of the former `--side` flag stays
+    accepted for back-compat. Case-insensitive. The mapping lives in the
+    CLI body, NOT in RcvSide — the enum stays the canonical Spanish
+    COMPRA/VENTA per the CONVENTIONS three-layer split (surface English,
+    internal Spanish).
+    """
+    mapping = {
+        "compras": RcvSide.COMPRA,
+        "compra": RcvSide.COMPRA,
+        "ventas": RcvSide.VENTA,
+        "venta": RcvSide.VENTA,
+    }
+    side = mapping.get(value.strip().lower())
+    if side is None:
+        raise ValueError(
+            f"invalid --type {value!r}: expected 'compras' or 'ventas' "
+            "(COMPRA/VENTA also accepted)."
+        )
+    return side
+
+
+@rcv_app.command(name="list")
+def rcv_list(
+    period: str = typer.Option(
+        ..., "--period", help="Tax period in YYYY-MM (e.g. 2026-06). Required."
+    ),
+    type_: str = typer.Option(
+        ...,
+        "--type",
+        "-t",
+        help="compras (DTEs you received) or ventas (DTEs you issued). "
+        "COMPRA/VENTA also accepted (case-insensitive).",
+    ),
+    codigo_tipo_doc: str = typer.Option(
+        ...,
+        "--doc-type-code",
+        help='SII DTE code (e.g. "33" Factura, "34" Exenta, "39" Boleta, '
+        '"61" Nota de Crédito). Use the codes surfaced by `sii rcv summary`.',
+    ),
+    rut: str | None = typer.Option(
+        None,
+        "--rut",
+        help="Operating RUT (e.g. 12345670-K). Defaults to the authenticated "
+        "RUT; see ADR-015 for the multi-RUT model.",
+    ),
+    fmt: _OutputFormat = typer.Option(
+        _OutputFormat.json,
+        "--format",
+        "-f",
+        case_sensitive=False,
+        help="Output format. JSON (default) includes the full `raw` payload "
+        "per row for tax-special cases; table shows the curated set.",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+) -> None:
+    """Per-DTE rows for one (period, --type, --doc-type-code).
+
+    Returns individual folios with counterparty RUT / razón social /
+    fechas / montos. PII surface: counterparty RUTs and razón social
+    are NOT redacted by default — pipe through jq or use `--format
+    table` if you need to filter.
+    """
+    if verbose:
+        logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    try:
+        side = _parse_rcv_type(type_)
+    except ValueError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+    try:
+        d = asyncio.run(
+            consultar_rcv_detalle(
+                period=period,
+                side=side,
+                codigo_tipo_doc=codigo_tipo_doc,
+                rut_operativo=rut,
+            )
+        )
+    except (CredentialNotFoundError, NotAuthenticatedError) as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+    except LoginFailedError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=3)
+    except RateLimitError as exc:
+        typer.secho(str(exc), fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(code=4)
+    except ValueError as exc:
+        typer.secho(f"invalid argument: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+    if fmt is _OutputFormat.json:
+        _print_rcv_detalle_json(d)
+    else:
+        _print_rcv_detalle_table(d)
+
+
+def _print_rcv_match_json(m: RcvMatchResult) -> None:
+    typer.echo(json.dumps(asdict(m), indent=2, ensure_ascii=False))
+
+
+def _print_rcv_match_table(m: RcvMatchResult) -> None:
+    """Curated human view: the headline `found`, then either the matched
+    row or an honest 'not found in <range>'. Full payload (incl. the
+    `raw` block of the matched row) is in `--format json`."""
+    typer.echo(f"folio:             {m.folio}")
+    typer.echo(f"rut:               {m.rut}")
+    if m.rut_emisor_filter:
+        typer.echo(f"rut emisor filter: {m.rut_emisor_filter}")
+    typer.echo(f"found:             {str(m.found).lower()}")
+    if m.found and m.row is not None:
+        r = m.row
+        typer.echo(f"period:            {m.period}")
+        typer.echo(f"side:              {m.side}")
+        typer.echo(f"código tipo doc:   {m.codigo_tipo_doc}")
+        typer.echo(f"rut emisor:        {r.rut_emisor or '-'}")
+        typer.echo(f"razón social:      {r.razon_social or '-'}")
+        typer.echo(f"fecha emisión:     {r.fecha_emision or '-'}")
+        typer.echo(f"monto total:       {r.monto_total if r.monto_total is not None else '-'}")
+    elif m.periods_searched:
+        typer.echo(
+            f"not found in {m.periods_searched[0]} → {m.periods_searched[-1]} "
+            f"({len(m.periods_searched)} months searched)"
+        )
+    else:
+        typer.echo("not found (no periods searched)")
+    if m.incomplete and not m.found:
+        typer.secho(
+            "warning: some RCV reads were rejected by SII — this negative is not "
+            "definitive (incomplete=true).",
+            fg=typer.colors.YELLOW,
+            err=True,
+        )
+
+
+@rcv_app.command(name="match")
+def rcv_match_cmd(
+    dte: int = typer.Option(
+        ..., "--dte", "--folio", help="DTE folio number to reconcile against the RCV."
+    ),
+    rut_emisor: str | None = typer.Option(
+        None,
+        "--rut-emisor",
+        help="Counterparty RUT (e.g. 12345670-K) to disambiguate when the same "
+        "folio number exists across different emisores. Filtered client-side.",
+    ),
+    range_from: str | None = typer.Option(
+        None,
+        "--from",
+        help="Search window start (inclusive) in YYYY-MM. Requires --to. "
+        "Defaults to the last 12 months.",
+    ),
+    range_to: str | None = typer.Option(
+        None,
+        "--to",
+        help="Search window end (inclusive) in YYYY-MM. Requires --from.",
+    ),
+    rut: str | None = typer.Option(
+        None,
+        "--rut",
+        help="Operating RUT (e.g. 12345670-K). Defaults to the authenticated "
+        "RUT; see ADR-015 for the multi-RUT model.",
+    ),
+    fmt: _OutputFormat = typer.Option(
+        _OutputFormat.json,
+        "--format",
+        "-f",
+        case_sensitive=False,
+        help="Output format. JSON (default) for machine consumption / piping to jq; "
+        "table for a curated human readout.",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+) -> None:
+    """Reconcile a DTE folio against the RCV — does SII have it, and where?
+
+    Searches RECEIVED DTEs (COMPRA side) for the folio across the period
+    window (default: the last 12 months), reusing ONE session paced per
+    ADR-011. Prints the matched row, or an honest "not found in <range>"
+    naming exactly the months searched. Use `--rut-emisor` to
+    disambiguate a folio that recurs across counterparties.
+    """
+    if verbose:
+        logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+
+    # --from / --to must come together; default window (last 12 months)
+    # is computed in the task when neither is supplied.
+    if (range_from is None) ^ (range_to is None):
+        typer.secho(
+            "invalid arguments: --from and --to must be supplied together.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+    window: tuple[str, str] | None = None
+    if range_from is not None and range_to is not None:
+        window = (range_from, range_to)
+
+    try:
+        m = asyncio.run(
+            consultar_rcv_match(
+                folio=dte,
+                rut_emisor=rut_emisor,
+                period_window=window,
+                rut_operativo=rut,
+            )
+        )
+    except (CredentialNotFoundError, NotAuthenticatedError) as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+    except LoginFailedError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=3)
+    except RateLimitError as exc:
+        typer.secho(str(exc), fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(code=4)
+    except ValueError as exc:
+        typer.secho(f"invalid argument: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+    if fmt is _OutputFormat.json:
+        _print_rcv_match_json(m)
+    else:
+        _print_rcv_match_table(m)
+
+
+def _print_f29_propuesta_json(p: F29Propuesta) -> None:
+    typer.echo(json.dumps(asdict(p), indent=2, ensure_ascii=False))
+
+
+def _print_f29_propuesta_table(p: F29Propuesta) -> None:
+    """Curated human view: header + the proposed código grid. The full
+    payload (incl. the listCodBase header PII) only shows in `--format json`
+    via the `raw` field."""
+    typer.echo(f"rut:               {p.rut}")
+    typer.echo(f"period:            {p.period}")
+    typer.echo(f"estado:            {p.estado if p.estado is not None else '-'}")
+    if p.descripcion_estado:
+        typer.echo(f"descripción:       {p.descripcion_estado}")
+    typer.echo(f"tipo propuesta:    {p.tipo_propuesta if p.tipo_propuesta is not None else '-'}")
+    typer.echo("")
+    if not p.codigos:
+        typer.echo("(no proposed códigos for this period)")
+        return
+    typer.echo(f"{'código':<8}  {'valor':>14}  {'glosa':<50}")
+    typer.echo("-" * 76)
+    for c in p.codigos:
+        typer.echo(
+            f"{c.codigo:<8}  "
+            f"{c.valor if c.valor is not None else '-':>14}  "
+            f"{(c.glosa or '-')[:50]:<50}"
+        )
+
+
+@f29_app.command()
+def draft(
+    period: str = typer.Option(
+        ..., "--period", help="Tax period in YYYY-MM (e.g. 2026-05). Required."
+    ),
+    rut: str | None = typer.Option(
+        None,
+        "--rut",
+        help="Operating RUT (e.g. 12345670-K). Defaults to the authenticated "
+        "RUT; see ADR-015 for the multi-RUT model.",
+    ),
+    fmt: _OutputFormat = typer.Option(
+        _OutputFormat.json,
+        "--format",
+        "-f",
+        case_sensitive=False,
+        help="Output format. JSON (default) includes the full `raw` payload "
+        "for tax-special cases; table shows the curated código grid.",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+) -> None:
+    """Read SII's pre-filled F29 (IVA mensual) propuesta for a period.
+
+    Read-only — never submits. Surfaces YOUR OWN tax position: the curated
+    output is the proposed código grid; the full payload (including the
+    header PII block) is in `raw` under `--format json`. Pipe through jq to
+    mask. Use `sii auth login` first if not authenticated.
+    """
+    if verbose:
+        logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    try:
+        p = asyncio.run(consultar_f29_propuesta(period=period, rut_operativo=rut))
+    except (CredentialNotFoundError, NotAuthenticatedError) as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+    except LoginFailedError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=3)
+    except RateLimitError as exc:
+        typer.secho(str(exc), fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(code=4)
+    except ValueError as exc:
+        typer.secho(f"invalid argument: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+    if fmt is _OutputFormat.json:
+        _print_f29_propuesta_json(p)
+    else:
+        _print_f29_propuesta_table(p)
+
+
+def main() -> None:
+    app()