Boring Budget Agent

Boring Budget Agent

Use this skill to run boring-budget commands with deterministic behavior for AI workflows.

Runtime environments

1. Repository mode:
   • The boring-budget repo is available locally.
   • Use docs/contracts/* as source of truth when needed.
2. Binary-only mode:
   • Only the boring-budget binary is available.
   • Do not assume repository files exist.
   • Use boring-budget --help plus --output json responses as runtime contract source.

Install and bootstrap (required)

1. Check availability:
   • command -v boring-budget
2. If missing, install before proceeding:
   • Homebrew: brew install guseducampos/tap/boring-budget
   • or download the release binary from GitHub Releases and put it on PATH
3. If Homebrew install fails, fall back to release binary installation and continue.
4. Verify installation:
   • boring-budget --help
5. Verify JSON mode:
   • run a lightweight command: boring-budget setup show --output json

Required operating mode

1. Prefer --output json for all automation flows.
2. Treat ok, warnings[], error, and meta as the canonical response envelope.
3. Persist and validate ledger money in minor units (amount_minor) with ISO currency codes.
4. Report contracts (report *, report export) expose monetary fields as major-unit strings (*_major).
   • Report payloads and report warning details never include *_minor keys.
   • data export --resource report --format csv uses *_major column names and two-decimal major-unit values.
   • Report balance fields include:
     • period_balance (selected scope net)
     • general_balance (lifetime context)
     • monthly_balance (monthly reports)
5. For command inputs, use decimal amount flags (--amount, --opening-balance, --month-cap) and rely on CLI-side deterministic conversion/validation to canonical amount_minor.
6. Legacy minor-unit input flags are removed from command input (--amount-minor, --opening-balance-minor, --month-cap-minor); do not use them.
7. When updating entry amounts, send --currency together with --amount so conversion is explicit and deterministic.
8. Use UTC-safe dates/timestamps for deterministic runs.
9. Never assume deletes are destructive:
   • deleting a category orphans linked entries
   • deleting a label removes links only
10. Treat overspend warnings as non-blocking writes (CAP_EXCEEDED warns, does not fail).
11. Schedule automation behavior:

• schedule add automatically ensures a managed user crontab entry exists on Linux/macOS.
• if crontab registration fails, schedule add fails (schedule is not created).
• schedules are monthly recurring templates; set --start-month equal to --end-month for one-time month-only behavior.

Standard execution flow

1. Ensure binary is available; install if missing (see install section).
2. Ensure setup exists (or run it once):
   • boring-budget setup show --output json
   • if missing, run setup init with explicit currency/timezone.
3. Use explicit flags in commands (no interactive assumptions).
4. On write commands, inspect warnings[] even when ok=true.
5. On failures (ok=false), branch from error.code and stable exit mapping.

High-value command patterns

# Setup
boring-budget setup init --default-currency USD --timezone America/New_York --output json

# Categories and labels
boring-budget category add "Food" --output json
boring-budget label add "Recurring" --output json

# Add income/expense entries
boring-budget entry add --type income --amount 3500.00 --currency USD --date 2026-02-01 --note "Salary" --output json
boring-budget entry add --type expense --amount 12.50 --currency USD --date 2026-02-11 --category-id 1 --label-id 1 --note "Lunch" --output json
boring-budget entry add --type expense --amount 74.25 --currency USD --date 2026-02-11 --note "Coffee" --output json
boring-budget entry add --type expense --amount 45.00 --currency USD --date 2026-02-11 --bank-account-id 1 --note "Fuel" --output json
boring-budget entry update 10 --bank-account-id 2 --output json
boring-budget entry update 10 --clear-bank-account --output json
boring-budget entry add --type expense --amount 95.00 --currency USD --date 2026-02-11 --payment-method card --card-id 1 --note "Groceries" --output json
boring-budget entry list --bank-account-id 1 --from 2026-02-01 --to 2026-02-28 --output json
boring-budget entry list --payment-method credit --from 2026-02-01 --to 2026-02-28 --output json

# Cap management (non-blocking overspend policy)
boring-budget cap set --month 2026-02 --amount 500.00 --currency USD --output json

# Setup with optional decimal onboarding values
boring-budget setup init --default-currency USD --timezone America/New_York --opening-balance 1000.00 --month-cap 500.00 --output json

# Card management and debt tracking
boring-budget card add --nickname "Main Credit" --last4 1234 --brand VISA --card-type credit --due-day 15 --description "Primary card" --output json
boring-budget card list --output json
boring-budget card update 1 --nickname "Main Visa" --output json
boring-budget card due show --card-id 1 --as-of 2026-02-10 --output json
boring-budget card debt show --card-id 1 --output json
boring-budget card payment add --card-id 1 --amount 200.00 --currency USD --note "Statement payment" --output json

# Reporting and balance
boring-budget report monthly --month 2026-02 --group-by month --output json
boring-budget report range --from 2026-02-01 --to 2026-02-28 --payment-method card --card-id 1 --output json
boring-budget balance show --scope both --from 2026-02-01 --to 2026-02-28 --output json
# report payload balance context: period_balance + general_balance (+ monthly_balance on monthly scope)

# Savings
boring-budget savings transfer add --amount 200.00 --currency USD --date 2026-02-12 --note "Emergency fund" --output json
boring-budget savings transfer add --amount 200.00 --currency USD --date 2026-02-12 --source-account-id 1 --destination-account-id 2 --note "Emergency fund" --output json
boring-budget savings entry add --amount 50.00 --currency USD --date 2026-02-13 --note "Gift saved" --output json
boring-budget savings entry add --amount 50.00 --currency USD --date 2026-02-13 --account-id 2 --note "Gift saved" --output json
boring-budget savings show --scope both --from 2026-02-01 --to 2026-02-28 --output json

# Bank accounts
boring-budget bank-account add --alias "Main Checking" --last4 1234 --output json
boring-budget bank-account link set --target general_balance --account-id 1 --output json
boring-budget bank-account link set --target savings --account-id 1 --output json
# same account can be linked to both spending and savings targets
boring-budget bank-account link list --output json
boring-budget bank-account balance show --scope both --from 2026-02-01 --to 2026-02-28 --output json

# Scheduled expenses
boring-budget schedule add --name "Rent" --amount 1500.00 --currency USD --day 5 --start-month 2026-02 --output json
boring-budget schedule add --name "One-time tax" --amount 300.00 --currency USD --day 20 --start-month 2026-04 --end-month 2026-04 --output json
boring-budget schedule run --through-date 2026-04-30 --output json
boring-budget schedule delete 1 --output json

# Portability
boring-budget data export --resource entries --format json --file /tmp/entries.json --output json
boring-budget data export --resource report --format json --file /tmp/report.json --report-scope monthly --report-month 2026-02 --report-group-by month --output json
boring-budget data backup --file /tmp/boring-budget.db --output json

Determinism checklist

• Use explicit date windows for reports and exports.
• Use stable label filtering mode when provided: any|all|none.
• Prefer fixed test dates instead of relative terms.
• Do not depend on object key order; do depend on documented schema.

Contract references

• Repository mode references:
  • JSON contracts: docs/contracts/README.md
  • Example payloads: docs/contracts/*.json
  • Error catalog: docs/contracts/errors.md
  • Exit codes: docs/contracts/exit-codes.md
• Binary-only fallback:
  • boring-budget --help for available commands and flags
  • infer errors from error.code and process exit code
  • use this stable exit map: 0=success, 1=internal, 2=invalid-argument, 3=not-found, 4=conflict, 5=db-error, 6=external-dependency, 7=config-error
• Task-specific playbook: {baseDir}/references/workflows.md

Converted and distributed by TomeVault — claim your Tome and manage your conversions.