aboutsummaryrefslogtreecommitdiffstats

firefly-cli

A command-line tool that lets an LLM agent (and you) interact with a Firefly III instance over its REST API. Python package, stdlib only, exposing the firefly command.

Install

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:

# 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:

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 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 file for the full text.