Guide · Agent skill
How to use the Firefly III Finance CLI agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The cli-anything-firefly-iii skill teaches an AI agent to run a command-line tool that works with a Firefly III personal finance app. It is for people who already run their own Firefly III server and want an assistant to list, create, update or review records in plain language. After this guide you will know what the skill does, how to install it, how to connect it to your server, and which safety precautions to take.
Firefly III Finance CLIHKUDS/CLI-Anything · Apache-2.0 Download the skill Quick start
- 1Download and unzip. Download the skill ZIP from this page and unzip it so the folder containing SKILL.md is available.
- 2Place the skill folder. Move it to ~/.claude/skills/ for personal use, or to a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Install the CLI. Run pip install cli-anything-firefly-iii with Python 3.10 or newer.
- 4Set your server and token. Export FIREFLY_III_BASE_URL and FIREFLY_III_PAT, or pass --base-url and --pat on each command.
- 5Test with a read-only request. Ask the agent to list your accounts or budgets to confirm it can reach your Firefly III instance.
- 6Make changes carefully. For updates or deletes, have the agent confirm the record ID and the exact change before it runs.
What the skill lets the agent do
The skill describes a command-line interface, cli-anything-firefly-iii, that wraps the Firefly III API. The agent can use it in place of you clicking through the web interface.
The command groups cover accounts, transactions, budgets, categories, tags, bills, piggy banks, currencies, recurring transactions, rules, rule groups, webhooks, summaries, insights, search, data export and system information. Most groups support create, read, update and delete, and some add extras such as budget limits, piggy bank events and rule testing or execution.
- Accounts, transactions, budgets, categories, tags and bills: list, get, create, update and delete
- Budgets also support limits, and piggy banks support events and adding money
- Rules and rule groups support test and execute actions
- Summaries, insights, search and export pull information from your data
Install the skill from the ZIP file
Download the ZIP file for the skill from this page and unzip it. The skill is delivered as a folder containing a SKILL.md file, which holds the instructions the agent reads.
For a personal setup, place the unzipped folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder instead.
In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Single project: the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload
Install the CLI and connect it to Firefly III
The skill needs the command-line tool itself. Install it with pip. You need Python 3.10 or newer and a running Firefly III instance.
Create a Personal Access Token (PAT) in your Firefly III instance. Then set two environment variables so the tool knows where your server is and how to authenticate. You can also pass the same values as command-line arguments instead.
Adding --json before a command makes the output machine-readable, which is how the agent is expected to read results.
- Python 3.10 or newer is required
- FIREFLY_III_BASE_URL is your server address, for example https://firefly.yourdomain.com
- FIREFLY_III_PAT is your personal access token
- Command-line alternatives: --base-url and --pat
pip install cli-anything-firefly-iii
export FIREFLY_III_BASE_URL="https://firefly.yourdomain.com"
export FIREFLY_III_PAT="your-personal-access-token"Ask the agent in plain language
Once the skill is installed and the tool is connected, you can make requests in ordinary language. The agent chooses the matching command group. Requests that name a specific record, such as a bill or budget, are easiest for it to match to the right command.
Behind the scenes the agent runs commands such as the ones below. You can also run these yourself to check what it will do.
- Show my asset accounts and their current balances
- List transactions from 1 January to 31 January
- Create a bill called Netflix at 15.99 per month
- Show my budgets and any limits set for this month
- Add 100 to my Vacation Fund piggy bank
cli-anything-firefly-iii --json accounts list --type asset
cli-anything-firefly-iii --json transactions list --start 2024-01-01 --end 2024-01-31
cli-anything-firefly-iii --json bills create --name "Netflix" --amount-min 15.99 --amount-max 15.99 --frequency monthlyReview what the agent is about to change
Update and delete commands change or remove records in your Firefly III data. The source does not describe an undo feature, so treat these as permanent. Before a destructive step, ask the agent to list or get the record first and confirm the ID.
Read-only requests such as listing, getting, searching, autocomplete and export are lower risk. Start with those to confirm the connection works before you allow changes.
- Check the ID with a list or get command before any delete
- Ask the agent to describe the change before it runs
- Begin with read-only requests to test the setup
cli-anything-firefly-iii --json budgets get --id 1Keep your token and machine secure
The skill runs scripts and sends network requests to the Firefly III server you configure. The token grants access to your full account, so anyone who has it can read and change your data.
Avoid putting the token in shared files or on shared or untrusted computers. Environment variables are the recommended way to supply it, according to the skill's own documentation.
- The skill runs scripts and uses the network
- The token gives access to the full account
- Do not share the token on shared or untrusted machines
What people use it for
- Asking for a plain-language summary of what you have spent or what budgets remain
- Recording a grocery transaction against a category and source account
- Checking upcoming bills and updating a bill amount when it changes
- Adding money to a piggy bank savings goal and reviewing its events
- Exporting data or searching transactions for a tax or review task
Frequently asked questions
Is the Firefly III CLI agent skill free?
The skill's source does not state a licence or price on the page you have, so check the repository for its licence terms. The underlying project is listed under the Apache-2.0 licence. You still need your own running Firefly III server.
What do I need to use the cli-anything-firefly-iii skill?
You need Python 3.10 or newer, the pip package cli-anything-firefly-iii, a running Firefly III instance, and a Personal Access Token. You also need to set FIREFLY_III_BASE_URL and FIREFLY_III_PAT or pass the equivalent command-line arguments.
Where do I put the skill folder for Claude?
For personal use, place the unzipped folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. In the Claude apps you can upload it under Settings → Capabilities → Skills.
Does this skill work without Firefly III?
No. The skill only talks to an existing Firefly III server and cannot provide finance data on its own. Without a running instance and a valid token, the commands have nothing to read or change.
Can the agent accidentally delete my financial records?
The skill includes delete and update commands, and these can permanently change or remove data. Limit the agent's actions by asking it to confirm IDs and changes first, and start with read-only requests.
How is this different from using the Firefly III web interface?
The skill lets an AI agent run the same kinds of operations through a command-line tool instead of you clicking through screens. It covers many areas of the API, including accounts, transactions, budgets, bills and rules.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you self-host Firefly III and want an AI agent to help record, search or summarise your finances, or if you want to script the API. Skip it if you do not run your own Firefly III server, or if you are not comfortable with an agent changing or deleting financial records and holding a token that grants full account access.
Download the skill