1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
---
name: firefly-cli
description: Operate a Firefly III instance from the command line via the `firefly` tool. Use when recording transactions, checking balances or accounts, or querying budgets/categories/tags in Firefly III, or whenever a personal-finance task mentions Firefly.
---
# firefly-cli
`firefly` is a stdlib-only Python CLI for a [Firefly III](https://www.firefly-iii.org/)
instance. It is built for an agent to drive: JSON in/out, names resolved to IDs,
clear exit codes. This skill tells you how to use it correctly.
## Setup check
Before anything, confirm it is configured:
```bash
firefly auth test
```
- Exit 0 with an `about` payload: ready.
- Exit 1 with `{"error": "No Firefly III config found..."}`: not configured.
Either run `firefly auth set` (interactive) or set `FIREFLY_URL` and
`FIREFLY_TOKEN` env vars. Do NOT invent a URL or token; ask the user.
If `firefly` is not on PATH, run from the repo with `python -m firefly_cli ...`
(same arguments) or `pip install -e .` first.
## The contract you rely on
- **Output is JSON by default.** Parse it. Lists return a flat array of
objects (`[{"id": "1", "name": "...", ...}]`); single resources return one
object. Do not pass `--human` when you intend to parse, it prints tables.
- **Exit code 0 = success, 1 = error.** On error, `{"error": "..."}` goes to
stderr. Always check the exit code before trusting output.
- **You pass names, not IDs.** `--from test01`, `--category Groceries`. The CLI
resolves them. An unknown or ambiguous name is a HARD error that lists the
candidates and exits 1. When that happens, read the candidates, pick the
right one, and retry. NEVER guess an account, a wrong account moves real
money.
- **`tx add` infers the transaction type** from the account types: asset to
expense = withdrawal, revenue to asset = deposit, asset to asset = transfer.
Override with `--type withdrawal|deposit|transfer` only when inference is
wrong or both ends are non-asset.
## Commands
```
firefly auth test verify connectivity and token
firefly account list [--type asset|expense|revenue|liability|...]
firefly account get <name|id>
firefly account balance <name|id>
firefly tx add <amount> --from <acct> --to <acct>
[--desc TEXT] [--date YYYY-MM-DD] [--category NAME] [--tags a,b] [--type T]
firefly tx list [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--account NAME] [--limit N]
firefly tx get <id>
firefly tx search <query>
firefly category list
firefly tag list
```
Global: `--human` (tables, do not use when parsing), `--url`/`--token`
(per-call override of config).
## Task recipes
**Record an expense** (most common):
```bash
firefly tx add 42.50 --from test01 --to Groceries --desc "weekly shop" --tags food
```
`test01` is an asset account, `Groceries` an expense account, so this is a
withdrawal. If `Groceries` does not exist, the CLI errors with the available
expense accounts; pick one or ask the user before creating a new category.
**Record income:**
```bash
firefly tx add 1800 --from Salary --to test01 --desc "June pay"
```
**Move money between own accounts:**
```bash
firefly tx add 200 --from test01 --to Savings --type transfer
```
**Check a balance:**
```bash
firefly account balance test01 # -> {"id","name","current_balance"}
```
**Find recent spending in a window:**
```bash
firefly tx list --account test01 --since 2026-06-01 --until 2026-06-30
```
**Look up a transaction by id** (ids come from `tx add`/`tx list` output):
```bash
firefly tx get 75
```
Returns a transaction group: `{"id", ..., "transactions": [ {split}, ... ]}`.
The real fields (type, amount, description, source/destination, tags) are in
`transactions[0]` for a single-split transaction.
## Gotchas
- `tx list` with no transactions in range returns `[]`. Empty is not an error;
it means no matches, not a failure.
- Amounts are strings in responses, often with trailing zeros
(`"0.010000000000"`). Compare numerically, do not string-match.
- Dates in `tx list` filter by transaction date; omit them to use Firefly's
default period, which may hide older transactions. Pass an explicit `--since`
to be sure.
- `--tags` is a single comma-separated argument: `--tags food,fun`.
## Extending
New verbs (budgets, bills, piggy banks, etc.) are added by dropping a module in
`firefly_cli/commands/`. See the project `CLAUDE.md` for the exact pattern.
|
