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
117
|
# firefly-cli
A command-line tool that lets an LLM agent (and you) interact with a
[Firefly III](https://www.firefly-iii.org/) instance over its REST API.
Python package, stdlib only, exposing the `firefly` command.
## Install
```bash
pip install -e .
```
Requires Python 3.11 or newer. No third-party runtime dependencies.
### Bash completion
A completion script lives at `completions/firefly.bash`. Enable it by sourcing
it from your shell profile, or install it system-wide:
```bash
# per-user: add to ~/.bashrc
source /path/to/firefly-cli/completions/firefly.bash
# or system-wide
sudo cp completions/firefly.bash /usr/share/bash-completion/completions/firefly
```
It is generated from the command registry, never hand-edited. Regenerate after
adding or changing commands:
```bash
python scripts/gen_completion.py > completions/firefly.bash
```
## Configuration
Provide your Firefly III URL and a personal access token in either way:
- Run `firefly auth set` and follow the prompts (stored in a local TOML file).
- Or set environment variables `FIREFLY_URL` and `FIREFLY_TOKEN`, which take
precedence over the config file.
## Commands
Run `firefly --help` for the full list. Current commands (v0.4.1):
```
firefly auth set write URL and token to the config file
firefly auth test verify connectivity and token
firefly account list [--type T] list accounts (filter: asset, expense, ...)
firefly account get <name|id> show one account
firefly account balance <name> show an account balance
firefly account create <name> --type asset|expense|revenue
[--opening-balance N] [--currency CODE]
firefly tx add <amount> --from <acct> --to <acct> [--desc T]
[--date YYYY-MM-DD] [--category C] [--tags a,b] [--type T]
[--budget B]
firefly tx list [--since D] [--until D] [--account A] [--limit N]
firefly tx get <id> show one transaction
firefly tx search <query> search transactions by Firefly query string
firefly tx edit <id> [--amount N] [--date D] [--desc T] [--from A]
[--to A] [--category C] [--tags a,b] [--budget B] [--type T]
firefly tx delete <id> --yes delete one transaction (requires --yes)
firefly budget list [--start D] [--end D]
list budgets with spent for a period (default: current month)
firefly budget create <name> [--active|--inactive] [--currency CODE]
[--auto-budget-amount N]
[--auto-budget-period daily|weekly|monthly|quarterly|half_year|yearly]
[--auto-budget-type reset|rollover|adjusted|none]
firefly budget update <name|id> [--name NEW] [--currency CODE]
[--auto-budget-amount N] [--auto-budget-period P] [--auto-budget-type T]
firefly budget enable <name|id> mark a budget active
firefly budget disable <name|id> mark a budget inactive
firefly budget delete <name|id> --yes
firefly budget limit-list <name|id>
firefly budget limit-set <name|id> --amount N [--start D] [--end D]
[--currency CODE]
firefly category list
firefly tag list
```
The command set grows over time; see `CLAUDE.md` for how to add one.
## For agents
- Output is JSON by default. Pass `--human` for aligned tables.
- Exit code is 0 on success, 1 on any error; errors print as
`{"error": "..."}` on stderr.
- Account arguments accept names, which are resolved to IDs. An ambiguous or
unknown account is a hard error listing the candidates, never a silent guess.
- Categories and tags are not resolved: `tx add --category`/`--tags` pass the
names straight to Firefly, which creates them if new. Accounts are never
auto-created; use `account create`.
- `tx add` infers the transaction type from the account types (asset to expense
is a withdrawal, revenue to asset is a deposit, asset to asset is a transfer).
Override with `--type`. `tx edit` changes only the fields you pass.
- Budgets are managed by name or id. `budget list` reports spent per budget for
a period; `budget limit-set` sets a spending limit over a date range.
`budget update` renames a budget or edits its auto-budget fields.
`budget delete` and `tx delete` require `--yes`.
## For agents (skill)
[`SKILL.md`](SKILL.md) is an agent-operating guide for driving `firefly`: the
JSON/exit-code contract, name resolution, transaction-type inference, task
recipes, and gotchas. It carries skill frontmatter, so it can be symlinked into
a Claude Code skills directory to auto-activate on Firefly III and personal
finance tasks.
## License
Released under the GNU General Public License, version 2 only (GPLv2-only).
See the [LICENSE](LICENSE) file for the full text.
|
