# Boring Budget Agent > Operate the boring-budget Go CLI in deterministic, agent-safe mode using stable JSON envelopes, exit/error codes, and non-destructive data semantics. Use when tasks involve setup, category/label/entry/cap workflows, reports and balances, or data import/export/backup/restore for boring-budget. Use when this capability is needed. - Skill: `tomevault-io/boring-budget-agent` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/boring-budget-agent` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/boring-budget-agent/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/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 ```bash # 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](https://tomevault.io/claim/guseducampos) — claim your Tome and manage your conversions.