Feat/add firefly iii cli

[joyous-coder]

Description

Add Firefly III personal finance management CLI based on CLI-Anything specification. Converts MCP mode to stateless CLI mode to avoid Node residual process issues.
Fixes #

Type of Change

• New Software CLI (in-repo) — adds a CLI harness inside this monorepo
• New Software CLI (standalone repo) — registry-only PR pointing to an external repo
• New Feature — adds new functionality to an existing harness or the plugin
• Bug Fix — fixes incorrect behavior
• Documentation — updates docs only
• Other — please describe:

---

For New Software CLIs (in-repo)

• <SOFTWARE>.md SOP document exists at <software>/agent-harness/<SOFTWARE>.md
• Canonical SKILL.md exists at skills/cli-anything-<software>/SKILL.md
• Packaged compatibility SKILL.md exists at cli_anything/<software>/skills/SKILL.md
• Unit tests at cli_anything/<software>/tests/test_core.py are present and pass without backend
• E2E tests at cli_anything/<software>/tests/test_full_e2e.py are present
• README.md includes the new software (with link to harness directory)
• registry.json includes an entry with source_url: null (see Contributing guide)
• repl_skin.py in utils/ is an unmodified copy from the plugin

For New Software CLIs (standalone repo)

• CLI is installable via pip install <package-name> or a pip install git+https://... URL
• SKILL.md exists in the external repo
• External repo has its own test suite
• registry.json entry includes source_url pointing to the external repo
• registry.json entry includes skill_md with full URL to the external SKILL.md
• install_cmd in registry.json works (tested locally)

For Existing CLI Modifications

• All unit tests pass: python3 -m pytest cli_anything/<software>/tests/test_core.py -v
• All E2E tests pass: python3 -m pytest cli_anything/<software>/tests/test_full_e2e.py -v
• No test regressions — no previously passing tests were removed or weakened
• registry.json entry is updated if version, description, or requirements changed

General Checklist

• Code follows existing patterns and conventions
• --json flag is supported on any new commands
• Commit messages follow the conventional format (feat:, fix:, docs:, test:)
• I have tested my changes locally

Test Results

$ pytest cli_anything/firefly_iii/tests/ -v
============================= test session starts =============================
platform win32 -- Python 3.14.4, pytest-9.0.3, pluggy-9.0.3
rootdir: D:\Links\Tools\CLI-Anything\firefly-iii\agent-harness
collected 37 items
cli_anything/firefly_iii/tests/test_core.py::TestFireflyIIIBackend::test_init_success PASSED [  2%]
cli_anything/firefly_iii/tests/test_core.py::TestFireflyIIIBackend::test_init_connection_error PASSED [  5%]
cli_anything/firefly_iii/tests/test_core.py::TestFireflyIIIBackend::test_init_auth_error PASSED [  8%]
cli_anything/firefly_iii/tests/test_core.py::TestFireflyIIIBackend::test_get_request PASSED [ 10%]
cli_anything/firefly_iii/tests/test_core.py::TestFireflyIIIBackend::test_post_request PASSED [ 13%]
cli_anything/firefly_iii/tests/test_core.py::TestOutput::test_json_output PASSED [ 16%]
cli_anything/firefly_iii/tests/test_core.py::TestOutput::test_human_readable_output PASSED [ 18%]
cli_anything/firefly_iii/tests/test_core.py::TestPresets::test_default_preset PASSED [ 21%]
cli_anything/firefly_iii/tests/test_core.py::TestPresets::test_full_preset PASSED [ 24%]
cli_anything/firefly_iii/tests/test_core.py::TestValidation::test_date_format PASSED [ 27%]
cli_anything/firefly_iii/tests/test_core.py::TestValidation::test_invalid_date_format PASSED [ 29%]
cli_anything/firefly_iii/tests/test_core.py::TestValidation::test_amount_format PASSED [ 32%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestE2E::test_connection PASSED [ 35%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestE2E::test_accounts_list PASSED [ 37%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestE2E::test_accounts_list_with_params PASSED [ 40%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestE2E::test_transactions_list PASSED [ 43%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestE2E::test_transactions_list_with_limit PASSED [ 45%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestE2E::test_budgets_list PASSED [ 48%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestE2E::test_categories_list PASSED [ 51%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestE2E::test_tags_list PASSED [ 54%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestE2E::test_bills_list PASSED [ 56%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestE2E::test_piggy_banks_list PASSED [ 59%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestE2E::test_insights_expense PASSED [ 62%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestE2E::test_insights_income PASSED [ 64%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestE2E::test_search PASSED [ 67%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestCLIE2E::test_cli_about PASSED [ 70%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestCLIE2E::test_cli_accounts_list PASSED [ 72%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestCLIE2E::test_cli_accounts_list_with_limit PASSED [ 75%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestCLIE2E::test_cli_transactions_list PASSED [ 78%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestCLIE2E::test_cli_budgets_list PASSED [ 81%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestCLIE2E::test_cli_categories_list PASSED [ 83%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestCLIE2E::test_cli_tags_list PASSED [ 86%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestCLIE2E::test_cli_bills_list PASSED [ 89%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestCLIE2E::test_cli_piggy_banks_list PASSED [ 91%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestCLIE2E::test_cli_insights_expense PASSED [ 94%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestCLIE2E::test_cli_search PASSED [ 97%]
cli_anything/firefly_iii/tests/test_full_e2e.py::TestCLIE2E::test_cli_info_status PASSED [100%]
============================= 37 passed in 35.77s =============================
Features
- Account Management: List, get, create, update, delete accounts
- Transaction Management: List, get, create, update, delete transactions
- Budget & Categories: Manage budgets and transaction categories
- Tags & Bills: Organize with tags, track recurring bills
- Piggy Banks: Savings goals tracking
- Insights & Reports: Expense/income analysis by category, date range
- Search: Full-text search across transactions
- Data Export: Export accounts, transactions, budgets, categories
- System Info: Check connection status and API version
Technical Details
- Stateless CLI Mode: Single call, immediate exit (no Node residual processes)
- Pure Python: No external dependencies beyond click, requests, prompt_toolkit
- Firefly III API v1: Full REST API integration
- Authentication: Personal Access Token (PAT)
- Python 3.10+: Modern Python support
Files Added
firefly-iii/
├── agent-harness/
│   ├── cli_anything/
│   │   └── firefly_iii/
│   │       ├── __init__.py
│   │       ├── __main__.py
│   │       ├── firefly_iii_cli.py      # Main CLI entry
│   │       ├── core/                    # Command groups
│   │       │   ├── accounts.py
│   │       │   ├── transactions.py
│   │       │   ├── budgets.py
│   │       │   ├── categories.py
│   │       │   ├── tags.py
│   │       │   ├── bills.py
│   │       │   ├── piggy_banks.py
│   │       │   ├── insights.py
│   │       │   ├── search.py
│   │       │   ├── export.py
│   │       │   └── info.py
│   │       ├── utils/
│   │       │   ├── firefly_iii_backend.py  # API client
│   │       │   └── repl_skin.py            # REPL UI
│   │       ├── tests/
│   │       │   ├── test_core.py            # Unit tests (12)
│   │       │   └── test_full_e2e.py        # E2E tests (25)
│   │       └── skills/
│   │           └── SKILL.md
│   ├── setup.py
│   └── README.md
└── skills/
    └── cli-anything-firefly-iii/
        └── SKILL.md
Testing Environment
- OS: Windows 11
- Python: 3.14.4
- Firefly III: v6.6.1
- Test Date: 2026-04-22

[yuh-yang]

Thanks for the Firefly III harness. Before merge, the default REPL needs to actually dispatch commands; right now it parses input and prints Executing: ... but does not run the selected command.

The harness also needs a registry.json entry, and the skill location should be reconciled with the repo's root skills/cli-anything-.../SKILL.md convention or the registry should point to the packaged skill consistently.