CLI Anything Firefly Iii
Apps & Automationcli-anything-firefly-iiiCLI Anything Firefly Iii is an Agent Skill for apps & automation published in the HKUDS/CLI-Anything repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Firefly III CLI - Personal finance management via CLI-Anything
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/HKUDS/CLI-Anything/blob/HEAD/firefly-iii/agent-harness/skills/cli-anything-firefly-iii/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/cli-anything-firefly-iii, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Firefly III CLI
Firefly III command-line interface based on CLI-Anything specification. Converts MCP mode to stateless CLI mode to avoid Node residual process issues.
Installation
pip install cli-anything-firefly-iii
Prerequisites
- Python 3.10+
- Running Firefly III instance
- Personal Access Token (PAT)
Configuration
Environment Variables (Recommended)
export FIREFLY_III_BASE_URL="https://firefly.yourdomain.com"
export FIREFLY_III_PAT="your-personal-access-token"
Command Line Arguments
cli-anything-firefly-iii --base-url https://firefly.yourdomain.com --pat your-token
Command Groups
| Command Group | Description | Corresponding API |
|---|---|---|
accounts | Account management | /api/v1/accounts |
transactions | Transaction management | /api/v1/transactions |
budgets | Budget management | /api/v1/budgets |
categories | Category management | /api/v1/categories |
tags | Tag management | /api/v1/tags |
bills | Bill management | /api/v1/bills |
piggy-banks | Piggy banks | /api/v1/piggy-banks |
insights | Insights and reports | /api/v1/insight/* |
search | Search | /api/v1/search/* |
export | Data export | /api/v1/data/export/* |
info | System information | /api/v1/about |
Usage Examples
Account Management
# List all accounts
cli-anything-firefly-iii --json accounts list
# List asset accounts
cli-anything-firefly-iii --json accounts list --type asset
# Get account details
cli-anything-firefly-iii --json accounts get --id 123
# Create account
cli-anything-firefly-iii --json accounts create --name "Cash" --type asset --currency-code USD
# Delete account
cli-anything-firefly-iii accounts delete --id 123
Transaction Management
# List transactions
cli-anything-firefly-iii --json transactions list --limit 10
# Create transaction
cli-anything-firefly-iii --json transactions create \
--description "Grocery" \
--amount 50.00 \
--source-account 1 \
--category "Food"
# Get transaction details
cli-anything-firefly-iii --json transactions get --id 456
# Delete transaction
cli-anything-firefly-iii transactions delete --id 456
Insights and Reports
# Expense report (by category)
cli-anything-firefly-iii --json insights expense \
--start 2024-01-01 \
--end 2024-01-31 \
--group-by category
# Income report
cli-anything-firefly-iii --json insights income \
--start 2024-01-01 \
--end 2024-01-31
# Account overview
cli-anything-firefly-iii --json insights overview \
--start 2024-01-01 \
--end 2024-01-31
Search
# Search transactions
cli-anything-firefly-iii --json search transactions --query "grocery"
Data Export
# Export transactions
cli-anything-firefly-iii --json export transactions \
--start 2024-01-01 \
--end 2024-01-31
# Export accounts
cli-anything-firefly-iii --json export accounts
System Information
# System information
cli-anything-firefly-iii --json info about
# Connection status
cli-anything-firefly-iii info status
Preset Filtering
Use --preset parameter to filter available commands:
# Default preset
cli-anything-firefly-iii --preset default accounts list
# Full preset
cli-anything-firefly-iii --preset full accounts list
# Budget preset
cli-anything-firefly-iii --preset budget budgets list
# Reporting preset
cli-anything-firefly-iii --preset reporting insights expense --start 2024-01-01 --end 2024-01-31
Available presets:
default: Core features (accounts, transactions, categories, tags, bills, search)full: All featuresbasic: Basic features (accounts, transactions, categories, tags, search)budget: Budget-related (accounts, budgets, transactions, summary, insight)reporting: Reporting-related (accounts, transactions, categories, insight, summary, search)admin: Admin features (about, configuration, currencies, users, preferences)automation: Automation (rules, recurrences, webhooks, transactions)
Agent Guidelines
Basic Usage
- Use
--jsonfor structured output: All commands support--jsonflag, returning JSON format data - Call
info statusfirst to check connection: Confirm Firefly III connection is normal before executing operations - Use presets to reduce command count: Filter unnecessary commands via
--preset
Common Workflows
View Account Balances
# 1. Check connection
cli-anything-firefly-iii info status
# 2. List asset accounts
cli-anything-firefly-iii --json accounts list --type asset
# 3. View account details (get balance)
cli-anything-firefly-iii --json accounts get --id <account_id>
Record Expense
# 1. Find expense accounts
cli-anything-firefly-iii --json accounts list --type expense
# 2. Create transaction
cli-anything-firefly-iii --json transactions create \
--description "Lunch" \
--amount 15.50 \
--source-account <asset_account_id> \
--destination-account <expense_account_id> \
--category "Food"
Monthly Report
# 1. Expense report
cli-anything-firefly-iii --json insights expense \
--start 2024-01-01 \
--end 2024-01-31 \
--group-by category
# 2. Income report
cli-anything-firefly-iii --json insights income \
--start 2024-01-01 \
--end 2024-01-31
# 3. Export data
cli-anything-firefly-iii --json export transactions \
--start 2024-01-01 \
--end 2024-01-31
Error Handling
Common errors and solutions:
- Connection failed: Check if FIREFLY_III_BASE_URL is correct
- Authentication failed: Check if FIREFLY_III_PAT is valid
- Resource not found: Check if ID is correct
- Parameter error: Check if required parameters are provided
Best Practices
- Use environment variables for credentials: Avoid exposing PAT in command line
- Use
--jsonfor scripting: Facilitates parsing and processing output - Use presets to control permissions: Choose appropriate preset based on scenario
- Query before modifying: Avoid accidental operations
Troubleshooting
Connection Issues
Error: Cannot connect to Firefly III instance
- Check if Firefly III instance is running
- Check network connection
- Check if base URL is correct
Authentication Issues
Error: Authentication failed: Personal Access Token is invalid
- Check if PAT is correct
- Generate new PAT in Firefly III Options > Profile > OAuth
- Ensure PAT has not expired
Comparison with MCP Version
| Feature | MCP Version | CLI-Anything Version |
|---|---|---|
| Process Lifecycle | Long-running | Single call, immediate exit |
| Memory Usage | Continuous | On-demand, released after |
| Communication | Stdio/SSE | Command args + stdout |
| State Management | Stateful | Stateless |
| Preset Filtering | Supported | Supported |
| JSON Output | Built-in | --json flag |
License
MIT License