# acc/0

> acc/0 is an AI bookkeeper for developers. Users forward bank statements,
> invoices and receipts; acc/0 extracts, categorises and reconciles them
> into a double-entry ledger, and NOTHING is booked until a human approves
> it in the app. Agents and the API can push documents, read proposals,
> export the ledger, and leave a comment on a proposal — they can never approve.
> That boundary is deliberate and permanent.

## The CLI — the agent's primary surface

One static binary over the v2 API. Full docs: https://acc0.dev/docs/cli.md

Install:

    curl -fsSL https://acc0.dev/install.sh | sh

Setup for an agent is one environment variable — no login, no config file,
no prompts ever:

    export ACC0_TOKEN=<api key>

(The user creates the key in the acc/0 app under Settings → API keys; it is
shown once at creation. Keys are org-scoped and read-only by default — an
agent that needs to push documents needs a key created with the read-write
scope.)

Commands:

    acc0 push <file>... [--account <id-or-slug>] [--json]   # upload receipts/invoices/statements
    acc0 incoming [--json] [--limit <n>] [--all] [--cursor <createdAt,id>]  # proposals awaiting human review
    acc0 status <documentId> [--json]               # poll one pushed document's pipeline status
    acc0 jobs [--failed] [--state <s>] [--json]     # the org's pipeline, newest first
    acc0 proposal <id> [--json]                     # full detail for one proposal
    acc0 export --account <id-or-slug> [--period all|month|quarter|fy]  # ledger CSV to stdout
    acc0 comment <proposalId> <message>             # leave a triage note on a proposal
    acc0 listen [--port 4242] [--secret <secret>]   # local webhook receiver (no key needed)
    acc0 docs [--agents]                            # print this reference from the binary
    acc0 help [command]
    acc0 --version

## The agent contract

These hold for every release with the same major version:

- Never prompts when stdin is not a TTY — a scripted call succeeds or
  fails, it never hangs.
- stdout carries data; stderr carries status and errors. stdout is always
  safe to parse or redirect.
- Piped `incoming` output is TSV, no header, columns in fixed order:
  `id  date  amountMinor  currency  description  confidence`. Columns are
  only ever appended.
- Money is exact: integer minor units (`amountMinor`), never floats.
- `--json` prints the raw API response verbatim (additive-only within v2).
- Exit codes: 0 success, 1 failure, 2 usage error (bad flags/args).
- Errors are single-line JSON (`{"error": "..."}`) on stderr when stderr
  is not a TTY, plain text when it is.

## The v2 API (what the CLI wraps)

Bearer auth with the same API key: `Authorization: Bearer acc0_sk_...`

- `POST https://acc0.dev/api/v2/documents` — multipart field `file` (or raw
  body + `X-Filename`); optional `account` (id or slug). Returns the
  documentId; processing is asynchronous. Costs one credit, charged when
  the extraction lands — a document we could not classify is handed back
  for you to retry or delete, and is never charged. `402` means the org has
  no credit and nothing was stored.
- `GET https://acc0.dev/api/v2/documents/<id>` — poll one document's pipeline
  status: `{ document, job }`, `job` is `null` until the pipeline
  claims it.
- `GET https://acc0.dev/api/v2/jobs?state=<state>&limit=<n>` — the org's
  pipeline jobs, newest first; `state` filters to one of the job-state
  enum.
- `GET https://acc0.dev/api/v2/proposals` — reconciliation proposals awaiting
  human review, org-wide, paginated by cursor.
- `GET https://acc0.dev/api/v2/proposals/<id>` — full detail for one proposal
  (every bank line, the linked document, category, reasoning, discussion).
- `GET https://acc0.dev/api/v2/export/ledger?account=<id-or-slug>&period=all|month|quarter|fy`
  — streamed CSV.
- `POST https://acc0.dev/api/v2/proposals/{id}/comment` — body `{"message":
  "..."}` (1-4000 chars); appends a note to the proposal's thread,
  attributed to the API key. 409 if the proposal is already approved or
  discarded.

There is no approve endpoint. Do not attempt to book, approve, or mutate
ledger entries — that capability does not exist outside the human app.

## Webhooks

`document.ingested` and `proposal.created`, HMAC-SHA256 signed
(`X-Acc0-Signature`), payloads carry IDs only. Details and a verification
snippet: https://acc0.dev/docs/webhooks.md

## Effective agent behaviour

- Push documents as the user acquires them; report the printed
  `path: documentId` lines back to the user.
- Read `acc0 incoming` and cross-check proposals against evidence you
  hold (invoices, payout reports); brief the user before THEY review — you
  cannot approve for them. `acc0 proposal <id>` gets the full picture
  (every bank line, the linked document, reasoning) when the list row is
  too thin to triage against. Found something? Run
  `acc0 comment <proposalId> "<note>"` to leave your findings on the
  proposal — the human sees them in Incoming.
- Answer money questions from `acc0 export` CSV; amounts are integer
  minor units.
- On failure, read stderr and the exit code; retry idempotent reads freely.
  Re-pushing identical bytes is also safe — it returns the same
  `documentId` instead of creating a duplicate.

## Pages

- Documentation index: https://acc0.dev/docs.md (HTML: https://acc0.dev/docs)
- CLI: https://acc0.dev/docs/cli.md (HTML: https://acc0.dev/docs/cli)
- Webhooks: https://acc0.dev/docs/webhooks.md (HTML: https://acc0.dev/docs/webhooks)
- Any docs page is also available as Markdown by appending `.md` to its URL.
- Product: https://acc0.dev (private beta)