← Back to Skills Marketplace

Firefly III API Client

Name: Firefly III API Client
Author: josetseph

by josetseph · GitHub ↗ · v1.0.5 · MIT-0

cross-platform ✓ Security Clean

128

Downloads

Stars

Active Installs

Versions

Install in OpenClaw

/install firefly-iii-published

Description

Access and manage Firefly III finance data programmatically, including transactions, accounts, recurring rules, and automation via the API.

README (SKILL.md)

Firefly III Client Skill

Purpose

A production-ready client for Firefly III personal finance management, allowing for programmatic access to transactions, accounts, recurring rules, and automation.

Security Considerations

See SECURITY.md for information on token safety, environment variables, and network security when using this skill.

Setup

Ensure Firefly III is running and you have an OAuth Personal Access Token.

Set the following environment variables:

FIREFLY_URL=http://your-instance-url
FIREFLY_TOKEN=your_personal_access_token

Install dependencies:
```
pip install requests
```

CLI Reference

The api.py script serves as a generic wrapper for the Firefly III REST API.

python3 api.py request \x3CMETHOD> \x3CENDPOINT> [-d \x3CJSON_DATA>]

Examples

List Accounts: python3 api.py request GET api/v1/accounts
Create Transaction: python3 api.py request POST api/v1/transactions -d '{"amount": "10.00", "description": "Coffee", "source_id": 1, "destination_id": 2, "date": "2026-04-06", "type": "withdrawal"}'
Create Recurring Transaction: python3 api.py request POST api/v1/recurrences -d '{"type": "withdrawal", "title": "Example", "first_date": "2026-04-30", "repeat_freq": "monthly", "nr_of_repetitions": 12, "repetitions": [{"type": "monthly", "moment": "30"}], "transactions": [{"description": "Item", "amount": "100.00", "source_id": 1, "destination_id": 2}]}'
Create Rule: python3 api.py request POST api/v1/rules -d '{"title": "Example Rule", "trigger": "destination_account_is", "value": "Netflix", "action": "link_to_bill", "action_value": "Netflix Bill"}'

Usage Guidance

This skill appears to be what it claims: a simple Firefly III API client. Before installing, ensure you: (1) only set FIREFLY_URL to a Firefly III instance you control or trust, (2) keep FIREFLY_TOKEN private (treat it like a password), (3) review the included openapi YAML if you are concerned about any documented internal hosts (it contains a 'do not use' internal URL but the code will not contact it unless you set FIREFLY_URL to that host), and (4) run the script in a trusted environment since it will perform authenticated network requests to the URL you supply. Also note the manifest version mismatch (1.0.3 vs registry 1.0.5) — this is likely harmless metadata drift but you may want to confirm you have the intended release.

Capability Analysis

Package: firefly-iii (xpi) Version: 1.0.3 Description: API client for Firefly III personal finance management. View accounts and transactions. The package is a standard API client for Firefly III, a personal finance management system. The source code consists of a Python script (src/api.py) that provides a command-line interface for making REST API requests to a user-specified Firefly III instance. It uses the 'requests' library for network communication and retrieves authentication credentials (URL and Token) from environment variables as documented. There is no evidence of malicious behavior such as secret exfiltration, unauthorized binary execution, or hidden payload downloads.

Capability Tags

cryptocan-make-purchasesrequires-oauth-token

Capability Assessment

✓ Purpose & Capability

Name/description, manifest, SKILL.md, and src/api.py all align: the skill implements a generic REST wrapper for Firefly III and requires FIREFLY_URL and FIREFLY_TOKEN. The declared capability (network.external) and the dependency on 'requests' are appropriate for this purpose. Minor metadata drift: manifest version (1.0.3) differs from registry version (1.0.5), which is a bookkeeping inconsistency but not a functional mismatch.

✓ Instruction Scope

SKILL.md directs the agent to set FIREFLY_URL and FIREFLY_TOKEN, install requests, and run api.py with explicit commands. The runtime instructions do not ask the agent to read unrelated files, system secrets, or transmit data to endpoints other than the configured FIREFLY_URL. The included SECURITY.md correctly warns about token safety.

✓ Install Mechanism

There is no automated install spec; the skill is instruction-only with an included Python script. Dependencies are modest (requests) and correctly declared in manifest. No external downloads or archive extraction are performed by the skill files.

✓ Credentials

The only environment variables declared and used are FIREFLY_URL and FIREFLY_TOKEN, which are necessary and proportionate for an API client. The code only reads those two variables and uses them to form authenticated requests.

✓ Persistence & Privilege

always is false and the skill does not request persistent system privileges or alter other skills or system configs. It performs network calls only to the user-provided FIREFLY_URL when invoked.

How to Use

Make sure OpenClaw is installed (local or Docker)
Run the install command in chat: /install firefly-iii-published
After installation, invoke the skill by name or use /firefly-iii-published
Provide required inputs per the skill's parameter spec and get structured output

Version History

v1.0.5

- Maintenance release with internal code changes in src/api.py. - No user-facing features or documentation updates.

v1.0.4

- Internal code changes made in src/api.py; user-facing functionality and documentation remain unchanged. - No updates to setup, usage examples, or CLI interface.

v1.0.3

- Updated manifest.json with minor adjustments (details not specified). - No changes to functionality or documentation were made. - Existing API usage and setup instructions remain unchanged.

v1.0.2

- Updated manifest.json file for improved configuration or compatibility. - No user-facing changes to functionality or documentation. - Maintained all instructions and CLI usage as in the previous version.

v1.0.1

- Added SECURITY.md with important security considerations. - Updated SKILL.md to reference SECURITY.md and highlight token, environment, and network security.

v1.0.0

Initial release of Firefly III Client Skill: - Provides a production-ready client for Firefly III personal finance management. - Enables programmatic access to transactions, accounts, recurring rules, and automation. - Includes a CLI wrapper (`api.py`) for making generic API requests. - Supports OAuth Personal Access Token authentication via environment variables. - Offers clear setup instructions and usage examples for common financial operations.

Metadata

Slug firefly-iii-published

Version 1.0.5

License MIT-0

All-time Installs 0

Active Installs 0

Total Versions 6

Frequently Asked Questions

What is Firefly III API Client?

Access and manage Firefly III finance data programmatically, including transactions, accounts, recurring rules, and automation via the API. It is an AI Agent Skill for Claude Code / OpenClaw, with 128 downloads so far.

How do I install Firefly III API Client?

Run "/install firefly-iii-published" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Firefly III API Client free?

Yes, Firefly III API Client is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does Firefly III API Client support?

Firefly III API Client is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Firefly III API Client?

It is built and maintained by josetseph (@josetseph); the current version is v1.0.5.

More Skills