gerardpaligot/accountant-toolkit/revolut-cli

Skill — Using the revolut CLI

What it is

revolut is a thin, deterministic command-line client of the official Revolut Business API (https://b2b.revolut.com/api/1.0). It prints the API's native JSON to stdout. It does no matching, interpretation, uploading or editing — it only reads. Use it for the fast, cheap, token-light read/inventory work; leave any judgement (matching a YAML to an expense, etc.) to yourself.

Read-only. The Revolut Business API has no receipt-upload or

expense-mutation endpoint. To attach a receipt or set a description you still

need the browser (see the revolut-attach-justificatifs-cli skill, which uses

this CLI for inventory and Playwright for the upload).

Prerequisites

1. revolut on the PATH. Check revolut --help. (Built from

packages/revolut-cli; npm install && npm run build, then npm link or an npm install exposes the revolut bin.)

1. Authenticated. Check revolut auth status. If hasRefreshToken: false, run

revolut auth setup once (one-time OAuth consent → stores a refresh_token). The access token (40-min lifetime) refreshes itself afterwards.

Command reference

revolut auth setup                          # one-time OAuth consent → store refresh_token
revolut auth status                         # report token validity (no secrets printed)
 
revolut expenses list --from <iso> --to <iso> [--state <state>] [--type <type>]
revolut expenses get <id>                   # full detail of one expense
 
revolut transactions list --from <iso> --to <iso> [--type <type>] [--account <id>]
revolut transactions get <id>
 
revolut receipts download <expenseId> --out <dir> [--receipt <id>]
 
revolut accounts list
revolut categories list                     # accounting categories (mapping reference)
revolut tax-rates list                      # VAT rates (reference)

Global flags (before the subcommand): --sandbox targets the sandbox host; --pretty renders a human table instead of JSON.

• --from / --to take ISO dates or date-times (2026-01-01). list commands

auto-paginate the whole window (no cursor handling needed).

• expenses list --state enum: missing_info (= UI "Information required"),

awaiting_review, reverted, pending_reimbursement, refund_requested, refunded, approved, rejected.

• --type enum (expenses & transactions): atm, card_payment, fee,

transfer, external, mileage_reimbursement.

Output

list commands print { "<resource>": [ … ] } — the API's native JSON, snake_case, verbatim. get prints the single object. Errors go to stderr with a non-zero exit code (no partial JSON on stdout). Pipe to jq to shape it.

Examples

# Expenses still needing info for January 2026 (the receipt-attach target set)
revolut expenses list --state missing_info --from 2026-01-01 --to 2026-02-01
 
# Compact triage view: date, merchant, amount, has-receipt, description
revolut expenses list --state missing_info --from 2026-01-01 --to 2026-02-01 \
  | jq -r '.expenses[] | [.expense_date, .merchant,
      (.spent_amount.amount|tostring)+" "+.spent_amount.currency,
      (if (.receipt_ids|length)>0 then "receipt" else "NO-receipt" end),
      (.description // "—")] | @tsv'
 
# Full detail of one expense (merchant, splits, category, tax_rate, receipt_ids…)
revolut expenses get 8f3c1e2a-1b4d-4c9a-9f21-7a6b5c4d3e2f
 
# Download the receipt(s) already attached to an expense
revolut receipts download 8f3c1e2a-… --out /tmp/revolut-receipts
 
# Category / tax-rate references (to map a fiche's category to Revolut's)
revolut categories list
revolut tax-rates list
 
# Sandbox + table output
revolut --sandbox --pretty transactions list --from 2026-01-01 --to 2026-02-01

Per-expense fields worth knowing (from expenses list / get)

Gotchas

• ❌ Don't expect it to upload/edit — read-only API. Writing is browser-only.
• ❌ Don't require strict amount equality in foreign currency — Revolut shows

the card amount (commission/FX included), which can differ from an invoice's EUR figure. Compare loosely; document the gap downstream.

• ❌ Don't re-list to "find what's done" — once a receipt+description are sent

in the UI, the expense leaves missing_info, so --state missing_info already excludes finished ones for free.

• If a command errors, read stderr — don't guess. Auth errors point to

revolut auth setup.

See also

• revolut-attach-justificatifs-cli — uses this CLI for inventory, Playwright for upload.
• packages/revolut-cli/README.md — install, auth, client regeneration.
• accountant-cli — the local YAML validator (different tool, different job).