Agent-ergonomic CLI for the SOS Contador accounting API (Argentina), built on the AXI conventions: token-efficient TOON output, structured errors on stdout, next-step hints, and no interactive prompts (except login, which the user runs in their own terminal).

Use

npx -y sosc-axi                # no install, always the latest release
npm install -g sosc-axi        # or install it as `sosc-axi`

The examples below use the installed sosc-axi; with npx, prefix them with npx -y.

Accounts and CUITs

SOS Contador authenticates a user (POST /login) and then each CUIT the user can access (GET /cuit/credentials/:idcuit). sosc-axi stores both tokens per account, so several users and CUITs can be used side by side. Passwords are never stored.

Log in from your own terminal, not through an agent: login prompts for the user and password, so the agent never sees them. Agents only use the stored session.

sosc-axi login                       # prompts for usuario and password
sosc-axi status                      # check the session and active CUIT against the API
sosc-axi cuits                       # CUITs the account can access
sosc-axi cuits use 20123456789       # select the working CUIT
sosc-axi cuits sct                   # AFIP SCT debt summary of the active CUIT (ccma: monotributo/autónomos)
sosc-axi login --usuario [email protected]   # add another account
sosc-axi accounts                    # list logged-in accounts
sosc-axi accounts use [email protected]
sosc-axi cuits --usuario [email protected]   # act as a non-default account
sosc-axi logout [--usuario <email>]

Sessions live in ~/.config/sosc-axi/accounts.json (mode 0600). Override with SOSC_AXI_HOME or XDG_CONFIG_HOME.

| Env | Purpose | | --- | --- | | SOSC_API_URL | API base URL (default https://api.sos-contador.com/api-comunidad) | | SOSC_DEBUG=1 | log API responses to stderr, tokens redacted |

Ventas, compras, cobros, pagos and recibos

Read-only listings and detail for the active CUIT, 50 rows per page:

sosc-axi ventas                                   # facturas of this month
sosc-axi ventas --modo notascredito --cae sincae --periodo mes_anterior
sosc-axi compras --desde 2026-01-01 --hasta 2026-03-31 --pagina 2
sosc-axi ventas --cliente 25101884 --desde 2026-01-01 --hasta 2026-06-30
sosc-axi ventas --puntoventa 5 --tipo F --numero 100-110   # this month unless --desde/--hasta
sosc-axi compras --proveedor 8769368 --tipo NC
sosc-axi ventas view 933742304                    # one invoice with imputaciones and productos
sosc-axi cobros --periodo mes_anterior            # money in
sosc-axi pagos view 930159905                     # one payment with imputaciones
sosc-axi recibos                                  # receipts, list only

--periodo is hoy, ayer, semana, mes (default) or mes_anterior; for ventas and compras --desde/--hasta (AAAA-MM-DD) selects a range instead (the API has no range for cobros, pagos and recibos). Ventas and compras also filter by --numero, --puntoventa, --tipo and --cliente/--proveedor (ids from sosc-axi clientes), within --desde/--hasta or this month.

Issuing ventas

ventas create issues a real fiscal document (factura, nota de crédito or nota de débito) from a JSON body shaped like PUT /venta in the API docs. It is validated before anything is sent:

sosc-axi ventas create --file venta.json --dry-run   # validate and show the request, send nothing
sosc-axi ventas create --file venta.json --cae       # create it and ask AFIP for the CAE
cat venta.json | sosc-axi ventas create --file -     # from stdin, saved without CAE
sosc-axi ventas cae 933742304                        # CAE, its expiry and any AFIP observation
sosc-axi ventas pdf 933742304                        # saves 933742304.pdf (--output <file>, - for stdout)
sosc-axi ventas email 933742304 933742305            # to the email on file of their cliente
sosc-axi ventas email 933742304 --email [email protected]

Each venta gets a uniqueid (a fresh UUID unless the JSON has one), so retrying with the same one does not create it twice. Use a test CUIT while trying this out.

Cuenta corriente

Balances per cliente or proveedor for the active CUIT, and the movements of one:

sosc-axi cuentacorriente                               # balance per cliente, this year
sosc-axi cuentacorriente --proveedores --pendientes    # unmatched supplier movements
sosc-axi cuentacorriente --clipro 25101884 --desde 2025-01-01   # movements with a running saldo

--desde defaults to January 1 of this year and --hasta to today; earlier movements fold into a "Saldo anterior" row.

IVA and AFIP e-ventanilla

Tax reports and the AFIP inbox for the active CUIT:

sosc-axi libroiva ventas --mes 09                 # Libro IVA Ventas of September, with totals
sosc-axi libroiva compras --ejercicio 2025        # the whole 2025 ejercicio
sosc-axi iva --mes 09                             # F2002: débito, crédito, retenciones and percepciones
sosc-axi eventanilla                              # AFIP communications of the last 30 days

--ejercicio defaults to this year and --mes (01-12) narrows it to one month. AFIP serves e-ventanilla only for the last 90 days, counted from today. sosc-axi <command> --help lists every flag.

Contabilidad

The books of the active CUIT, read-only:

sosc-axi asientos --periodo mes_anterior          # journal entries, 50 per page
sosc-axi asientos view 951099901                  # one asiento with its imputaciones
sosc-axi mayor 01.01.01.003.001                   # libro mayor of one cuenta, whole ejercicio
sosc-axi mayor 01.01.01 --ejercicio 2025          # every cuenta under a rubro
sosc-axi sumasysaldos --desde 2026-09-01 --hasta 2026-09-30   # trial balance with totals

asientos --periodo adds anio (last calendar year) to the usual periods; the API has no date range for asientos. The API ignores dates for the mayor, so it always covers the whole --ejercicio (default this year); use sumasysaldos for a range. sumasysaldos balances start at 0 on --desde: the asiento de apertura only counts from the start of the ejercicio.

Clientes, productos, cuentas and centros de costo

Master data of the active CUIT, read-only:

sosc-axi clientes                                 # clientes and proveedores, 50 per page, each tagged cliente/proveedor/ambos
sosc-axi clientes --tipo proveedor --pagina 2
sosc-axi productos                                # id, price and IVA rate
sosc-axi puntosventa                              # number and name
sosc-axi cuentas                                  # plan de cuentas: codes for sosc-axi mayor
sosc-axi centroscosto
sosc-axi modificadores                            # grupos de modificadores with their modifier productos and prices

Reference tables, read-only:

sosc-axi unidades                                 # AFIP units of measure
sosc-axi provincias                               # ids for idprovinciaiibb
sosc-axi indices                                  # índices de ajuste por inflación per month, with axic/axii
sosc-axi actividades panaderia                    # AFIP actividades by description: code and name
sosc-axi tipos condicioniva                       # id and name of a parameter table; `tipos --help` lists the modulos
sosc-axi tipos creditofiscal bienes

Searches drop accents: the API finds nothing when the text has them. Without the search text, both list everything.

Without --tipo, clientes also reads both side lists in full to label rows, so it makes extra API calls. Above 25,000 rows per side it fails with API_ERROR; pass --tipo then.

API spec

openapi/sos-contador.openapi.yaml is generated from the official Postman documentation, whose raw collection is kept next to it. Do not edit either file by hand.

bun run sync:openapi            # fetch upstream and regenerate
bun run sync:openapi --check    # fail if stale

A weekly GitHub Action opens a PR when upstream changes.

Development

Bun is the dev toolchain; the published binary runs on Node >= 20 (that is what npx uses), so src/ must stick to node:* APIs.

bun install
bun run dev -- <command>   # run from source
bun test
bun run typecheck
bun run lint               # Biome lint + format check (lint:fix to apply)
bun run build              # dist/sosc-axi.js

Agent skill

skills/sosc-axi/SKILL.md ships in the npm package and the repo so agents know when to reach for the CLI. It is a short stub that points at sosc-axi --help (which never goes stale) and is generated from src/skill.ts:

bun run build:skill            # regenerate after changing src/skill.ts or the CLI description
bun run build:skill --check    # fail if stale (also covered by bun test)

Releases

Releases are cut by release-please from Conventional Commits on main and published to npm latest. While on 0.x:

• fix:, feat: -> patch (0.1.1 -> 0.1.2)
• feat!: / BREAKING CHANGE: -> minor (0.1.x -> 0.2.0)
• docs:, chore:, ci:, test:, refactor: -> no release on their own

Every push to main updates a release PR with the next version and the CHANGELOG.md entry. Merging it tags the release, creates the GitHub release and publishes to npm with provenance. CHANGELOG.md and .release-please-manifest.json are generated, never edit them (CI rejects PRs that do).

License

MIT