Output and scripting

Every command prints a table or a short summary for people. --json prints JSON for scripts, and every list can also write CSV.

Rules scripts can rely on#

Data goes to stdout; everything else goes to stderr. That includes the (using Actual credentials from …) line, errors, and the Actual engine's own messages, so piped output stays clean.
Exit status is 0 on success and 1 on any error.
No prompts during normal commands. Destructive commands need --yes rather than asking. (auth login without --password is the one interactive command.)

Money is in minor units#

Actual stores amounts as integers in the currency's smallest unit: -4250 means −42.50.

Tables format amounts: -42.50, 6,735.77.
--json and CSV keep Actual's integers, so nothing is lost to rounding.
On the command line you type decimals: --amount -42.50, --amount 1250.00.
Import and add files (--file) use integers, like Actual's own API.

Lists#

Every list command takes:

Option
`--json`	JSON wrapped in an object, such as `{ "accounts": [...] }`
`--format table\|csv\|json`	Choose the format. `--format json` is the same as `--json`
`--fields a,b,c`	Choose and order the columns
`--output <file>`	Write to a file instead of stdout
`--limit <n>`	Keep the first `n` rows

fob-actual payees list --format csv --output payees.csv
fob-actual accounts list --fields name,balance
fob-actual transactions list --account Checking --from 2026-01-01 --format csv --output 2026.csv

--limit trims after the full result is read from the local copy; there's no paging.

JSON shapes#

Lists wrap their rows in an object named after the resource:

fob-actual accounts list --json | jq '.accounts[] | {name, balance}'
fob-actual transactions list --account Checking --json | jq '.transactions | length'

Transactions in JSON carry IDs, not names: payee, category and account are IDs. The table resolves them to names for reading. Use payees list --json and categories list --json to map them, or use Query, which can select payee.name and category.name directly.

With jq#

# Total spent per payee in September, in currency units
fob-actual query run --table transactions \
  --filter '{"date":{"$gte":"2026-09-01"}}' --filter '{"date":{"$lte":"2026-09-30"}}' \
  --filter '{"amount":{"$lt":0}}' --select payee.name,amount --json \
  | jq -r '.data | group_by(.["payee.name"]) | map({payee: .[0]["payee.name"], total: (map(.amount) | add / -100)}) | sort_by(-.total) | .[] | "\(.total)\t\(.payee)"'