<p align="center"> <img src="docs/_static/readme/cadrumo-logo.svg" alt="Cadrumo logo" width="136"> </p>

Cadrumo: turn Spanish tax records into locally verified filing artifacts

Cadrumo turns local financial records into calculated, checked, and exportable artifacts for supported Spanish tax forms. It keeps the calculation path deterministic and preserves each result's sources.

Use Cadrumo to prepare a filing workspace, review the figures, and export a local file. You remain responsible for deciding what to file.

[!IMPORTANT] Cadrumo never submits a filing. Review every result, then file through official Agencia Estatal de Administración Tributaria (AEAT) channels.

Cadrumo is independent from AEAT and isn't affiliated with or endorsed by the authority. It doesn't provide tax, legal, accounting, or financial advice.

Public publishing remains blocked while package, repository, marketplace, domain, executable, and trademark gates are unresolved. Install Cadrumo only from an authorized source checkout.

Understand the names

• Cadrumo is the product. Its package, distribution, repository, and plugin use the machine identifier cadrumo. Its permanent command-line interface (CLI) command is aeat.
• AEAT is Spain's tax authority. The name remains in official portals, credentials, evidence, citations, and legal terminology.
• A profile isolates one taxpayer's local settings, records, and filing workspaces.
• A modelo is a Spanish tax form. A casilla is one registered field in that form.
• A verified calculation revision is a saved calculation for which Cadrumo recorded a complete verification report. It isn't proof of filing or AEAT acceptance.

Run Cadrumo from source

Cadrumo requires Python 3.13 or later and uses uv for its local environment.

From an authorized source checkout, run:

python --version
uv sync
uv run aeat --version
uv run aeat --help

The aeat --version command verifies that aeat launches the Cadrumo CLI and reports CADRUMO followed by the installed version. The aeat --help command displays the Cadrumo command tree and options.

If you choose encrypted file storage, or Cadrumo falls back to it, the first command that opens local storage asks for a master-key passphrase. That passphrase unlocks the locally encrypted records. Operating-system-backed secret stores use their own unlock flow.

Don't install from the Python Package Index or a public plugin marketplace yet. A successful local build doesn't clear Cadrumo's publication gates.

Complete one local filing path

The following example uses fictional data to prepare Modelo 130 for the first quarter of 2026. It writes a local fichero-BOE, an AEAT-compatible, fixed-width filing file with the .boe extension. BOE stands for Boletín Oficial del Estado.

Long PowerShell commands use backticks for line continuation. Copy each complete block, including every backtick.

1. Create a profile

uv run aeat config profile create demo `
  --quiet --accept-defaults `
  --entity-type natural_person `
  --tax-id 12345678Z --name Ana --surnames "García López" `
  --activity consultoria --activity-start-date 2026-01-01 `
  --irpf-income-categories actividad_economica `
  --tax-residence-ccaa madrid

The profile becomes active. It is the storage authority for records you create or change and for the filing workspace. Read-only commands inspect that profile without creating records. Export writes the cleartext .boe file to the path you choose with --output.

2. Add two classified records

uv run aeat app ledger add `
  --date 2026-02-10 --amount 1210 --direction INCOMING `
  --description venta --classification BUSINESS `
  --taxable-base 1000 --iva-rate 0.21 --iva-amount 210