diff options
Diffstat (limited to 'SKILL.md')
| -rw-r--r-- | SKILL.md | 52 |
1 files changed, 50 insertions, 2 deletions
@@ -52,12 +52,17 @@ If `firefly` is not on PATH, run from the repo with `python -m firefly_cli ...` firefly auth test verify connectivity and token firefly account list [--type asset|expense|revenue|liability|...] firefly account get <name|id> -firefly account balance <name|id> +firefly account balance <name|id> [--at YYYY-MM-DD] firefly account create <name> --type asset|expense|revenue [--opening-balance N] [--currency CODE] firefly tx add <amount> --from <acct> --to <acct> [--desc TEXT] [--date YYYY-MM-DD] [--category NAME] [--tags a,b] [--type T] -firefly tx list [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--account NAME] [--limit N] + [--dry-run] [--skip-dupes] +firefly tx edit <id> + [--amount N] [--date YYYY-MM-DD] [--desc TEXT] [--from <acct>] [--to <acct>] + [--category NAME] [--tags a,b] [--type T] # only fields passed are changed +firefly tx delete <id> --yes # --yes required, no prompt +firefly tx list [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--account NAME] [--limit N] [--all] firefly tx get <id> firefly tx search <query> firefly category list @@ -87,6 +92,10 @@ firefly tx add 1800 --from Salary --to test01 --desc "June pay" ```bash firefly tx add 200 --from test01 --to Savings --type transfer ``` +For a transfer, `tx add` echoes `transfer: <from> → <to>, <amount>` to stderr +before writing (also in `--dry-run`) so a swapped `--from`/`--to` is caught +before it silently drifts balances by 2x the amount. stdout JSON is unchanged; +the hint is on stderr only. **Create an account** (when `tx add` errors that an account does not exist, and the user confirms it should be created): @@ -98,9 +107,29 @@ Supports asset, expense, revenue. asset accounts get the default role automatically. Unlike categories/tags, accounts are NOT auto-created by `tx add`, create them explicitly here first. +**Validate a batch before writing any of it:** when importing many rows in a +loop, a mid-batch failure (a `--to` account that doesn't exist yet) leaves the +earlier rows already written. Dry-run each row first so the whole batch fails +fast: `tx add ... --dry-run` resolves `--from`/`--to` and infers the type but +sends nothing, printing `{"dry_run": true, "would_send": {...}}`. A missing +account is still a hard error (exit 1). Recipe: dry-run every row, create any +accounts the errors name, then run the batch for real. + +**Idempotent re-runs (avoid duplicate rows):** re-importing the same rows +(a retried or double-read batch) otherwise creates phantom duplicates and +drifts balances. Pass `--skip-dupes` to `tx add`: before writing it searches +for an existing tx with the same amount + date + source + destination, and if +one is found emits `{"skipped": "duplicate", "matched_id": "<id>"}` and exits 0 +without writing. Off by default (one extra search per add only when set). Note +it matches amount+date+accounts, not description, so two genuinely distinct +purchases of the same value, same day, between the same accounts look like a +duplicate; omit `--skip-dupes` where that is expected. + **Check a balance:** ```bash firefly account balance test01 # -> {"id","name","current_balance"} +firefly account balance test01 --at 2026-05-31 # historical: balance as of that date + # -> adds "date"; useful for reconciliation ``` **Find recent spending in a window:** @@ -116,16 +145,35 @@ Returns a transaction group: `{"id", ..., "transactions": [ {split}, ... ]}`. The real fields (type, amount, description, source/destination, tags) are in `transactions[0]` for a single-split transaction. +**Fix a mis-imported transaction.** `tx edit` patches only the fields you pass; +everything else is left untouched. To flip a reversed transfer, swap the ends: +```bash +firefly tx edit 75 --from BBVA --to Mediolanum +firefly tx edit 75 --amount 50.00 --date 2026-06-15 +firefly tx delete 76 --yes # remove a duplicate +``` + ## Gotchas - `tx list` with no transactions in range returns `[]`. Empty is not an error; it means no matches, not a failure. +- `tx list` returns at most `--limit` rows (default 20). When more match, it + prints `showing N of M (use --all for all)` to **stderr** (stdout JSON stays + clean). Pass `--all` to auto-paginate every page. Critical for reconciliation: + a truncated list makes a correct ledger look wrong. - Amounts are strings in responses, often with trailing zeros (`"0.010000000000"`). Compare numerically, do not string-match. +- A missing or deleted transaction id returns `API error 401: Unauthenticated.` + (not 404) on `tx get`/`tx edit`/`tx delete`. This is a Firefly quirk, not an + auth failure: if other commands work, the id simply does not exist. After a + `tx delete`, a 401 on that id confirms it is gone. - Dates in `tx list` filter by transaction date; omit them to use Firefly's default period, which may hide older transactions. Pass an explicit `--since` to be sure. - `--tags` is a single comma-separated argument: `--tags food,fun`. +- `tx edit` handles single-split journals only. `tx delete` will not run + without `--yes` (there is no interactive prompt); on success it prints + `{"deleted": "<id>"}`. ## Extending |