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 how to operate a command-line tool that connects to your own Firefly III personal finance server. This guide covers what the skill lets the agent do, how to install it, how to trigger it with plain requests, and the safety points to check before giving an agent access to your financial records. After following it, you will have a working connection and know how to ask for common tasks.
Firefly III Finance CLIHKUDS/CLI-Anything · Apache-2.0 Download the skill Quick start
- 1Confirm prerequisites. Make sure Python 3.10 or newer is installed and that your Firefly III instance is running and reachable.
- 2Install the tool. Run pip install cli-anything-firefly-iii in your terminal.
- 3Install the skill folder. Download the ZIP from this page, unzip it, and place the folder in ~/.claude/skills/ or a project's .claude/skills/, or upload it under Settings → Capabilities → Skills.
- 4Set your connection details. Export FIREFLY_III_BASE_URL and FIREFLY_III_PAT, using a Personal Access Token from Firefly III under Options > Profile > OAuth.
- 5Check the connection. Ask the agent to check the connection, which runs the info status command before any other operation.
- 6Make a request. Ask a plain question such as listing asset accounts or running an expense report for a date range.
What does the Firefly III CLI agent skill do?
An agent skill is a folder with a SKILL.md file that tells an AI agent how to use a tool. This skill describes a Firefly III command-line interface built on the CLI-Anything specification. The agent calls the tool, which talks to an existing Firefly III instance and returns results.
The command groups cover accounts, transactions, budgets, categories, tags, bills, piggy banks, insights (reports), search, data export and system information. Commands can return structured JSON when the --json flag is used.
- List, get, create and delete accounts
- List, get, create and delete transactions
- Run expense and income reports and an account overview
- Search transactions and export transactions or accounts
Install the skill and the command-line tool
Download the skill ZIP from this page and unzip it. Place the resulting skill folder in ~/.claude/skills/ for all projects, or in a project's .claude/skills/ folder for one project only. Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
The skill also needs the command-line tool itself. The SKILL.md file lists the Python package cli-anything-firefly-iii as installable with pip. Python 3.10 or newer is required.
- Python 3.10 or newer
- A running Firefly III instance
- A Firefly III Personal Access Token
pip install cli-anything-firefly-iiiConnect the tool to your Firefly III server
The SKILL.md recommends setting two environment variables: the base URL of your Firefly III instance and your Personal Access Token. You can also pass the same values as command-line arguments. Generate a token in Firefly III under Options > Profile > OAuth.
Run info status first. The skill's agent guidelines say to confirm the connection before running other operations.
- Use environment variables for credentials where possible, since the source advises against exposing the token on the command line
- If the connection fails, check that the base URL is correct and the instance is running
- If authentication fails, check that the token is valid and has not expired
export FIREFLY_III_BASE_URL="https://firefly.yourdomain.com"
export FIREFLY_III_PAT="your-personal-access-token"How do you trigger the skill with natural requests?
You do not need to type commands yourself. Ask the agent in plain language about your budget, and it should use the skill when the request matches the tool's capabilities. Mention Firefly III or your finances so the agent knows which tool to use.
For changes, the agent should query first. The source's guidelines say to look up accounts and IDs before creating or modifying records, so you may see several calls before a transaction is recorded.
- "Check my Firefly III connection and list my asset accounts."
- "Record a 15.50 lunch expense from my checking account in the Food category."
- "Give me an expense report by category for last month and export the transactions."
- "Search my Firefly III transactions for grocery purchases."
Safety notes: scripts, network and destructive commands
The skill runs scripts and uses the network. It sends requests to the Firefly III address you configure, so only point it at a server you trust. The skill includes create and delete commands for accounts and transactions, which change real financial data. Review what the agent plans to run before approving changes.
The source notes that the token can be exposed through environment variables or command arguments. Avoid running this on shared or public machines.
- Delete commands (accounts delete, transactions delete) cannot be undone by the skill
- Use presets such as reporting or budget to limit which command groups are available
- Ask the agent to query before modifying records
What people use it for
- Asking for a monthly expense breakdown by category and a matching income report
- Recording everyday expenses such as lunch or groceries with a category attached
- Searching past transactions for a merchant or keyword
- Exporting transactions for a date range to use in a spreadsheet or script
Frequently asked questions
Is the Firefly III CLI agent skill free to use?
The repository listing shows an Apache-2.0 licence, but the SKILL.md file's License section says MIT License. Check the LICENSE file in the repository before relying on either. You also need a running Firefly III instance, which you host yourself.
What do I need to install the Firefly III agent skill?
You need Python 3.10 or newer, a running Firefly III instance, and a Firefly III Personal Access Token. Install the tool with pip install cli-anything-firefly-iii, then place the skill folder in your Claude skills directory.
Where do I put the skill folder?
Put it in ~/.claude/skills/ to make it available across projects, or in a project's .claude/skills/ folder to limit it to that project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
How do I get a Firefly III Personal Access Token?
In Firefly III, go to Options > Profile > OAuth and generate a new Personal Access Token. Store it in the FIREFLY_III_PAT environment variable. If authentication fails later, the token may be invalid or expired, so generate a new one.
Can the agent delete my data?
Yes. The skill includes delete commands for accounts and transactions. Use a limited preset such as reporting or budget if you want to reduce what the agent can run, and review destructive actions before approving them.
How is this different from the MCP version of Firefly III tools?
The source says the CLI version runs as a single call that exits immediately and is stateless, while the MCP version is long-running and stateful. The CLI version uses command arguments and stdout with a --json flag for structured output.
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
This skill suits people who self-host Firefly III and want an agent to query budgets, record transactions or generate monthly reports, especially if they can review changes before they are made. It is not a good fit if you do not run a Firefly III server, if you are not comfortable letting an agent write to financial records, or if you work on a shared machine where your token could be seen.
Download the skill