budgetbakers-wallet-cli

Malé CLI pro BudgetBakers Wallet REST API.

Je dělané hlavně pro shell, automatizaci a AI agenty, ale bez problému se dá používat i ručně z terminálu.

CLI příkaz v terminálu je bbwallet.

Pokud chcete přes jedno API pracovat s daty z českých bank, Wallet od BudgetBakers je docela praktická vrstva. BudgetBakers řeší napojení i hosting, ve Walletu si propojíte účty a přes REST API nebo tohle CLI si pak můžete tahat data do skriptů, dashboardů nebo vlastní automatizace.

Hodí se to hlavně ve chvíli, kdy máte ve Walletu napojené účty z Fiobanky, Komerční banky, České spořitelny, ČSOB, Air Bank, Monety, mBank, Raiffeisenbank nebo Revolutu a nechcete řešit integraci pro každou banku zvlášť.

Tohle CLI je read-only. Není to oficiální SDK žádné konkrétní banky. Je to malé CLI nad Wallet API, které má dát rozumné rozhraní pro běžné použití v terminálu a ve skriptech.

CLI je schválně tenké a drží se veřejného Wallet API:

• stabilní JSON výstup
• explicitní podpříkazy
• předvídatelné chyby a exit kódy
• jednoduché lokální přihlášení s uložením tokenu mimo repozitář
• ergonomické flagy místo syrových API filtrů

--help je textový. Výstupy příkazů i chyby jsou v JSONu.

Rychlý přehled příkazů

bbwallet auth login [--no-open]
bbwallet auth status
bbwallet auth logout

bbwallet accounts list [flags]
bbwallet categories list [flags]
bbwallet budgets list [flags]
bbwallet goals list [flags]
bbwallet labels list [flags]
bbwallet standing-orders list [flags]
bbwallet record-rules list [flags]

bbwallet records list [flags]
bbwallet records get <record-id>
bbwallet records get-many --id <id[,id2,...]>

bbwallet usage stats --period <30days|4weeks|6months>

bbwallet resolve account <query> [--exact] [--currency-code <code>]
bbwallet resolve category <query> [--exact]
bbwallet resolve label <query> [--exact]

bbwallet report spending-by-category --from YYYY-MM-DD --to YYYY-MM-DD [flags]
bbwallet report by-account --from YYYY-MM-DD --to YYYY-MM-DD [flags]
bbwallet report top-counterparties --from YYYY-MM-DD --to YYYY-MM-DD [flags]
bbwallet report monthly-summary --from YYYY-MM-DD --to YYYY-MM-DD [flags]

Help pro konkrétní skupinu příkazů:

bbwallet --help
bbwallet auth --help
bbwallet records --help
bbwallet report --help

Proč to existuje

Wallet REST API je použitelné samo o sobě, ale v praxi kolem něj zůstává pár věcí, které v CLI a automatizaci zbytečně otravují:

• správa bearer tokenu
• syntaxe filtrů jako gte., lte. nebo contains-i.
• ruční stránkování
• metadata v hlavičkách odpovědi
• několik výpisových endpointů s lehce odlišným tvarem odpovědi

bbwallet tohle schová a dá nad tím jednoduchý, opakovatelný příkazový povrch.

Požadavky

• Node.js 20+
• API token pro BudgetBakers Wallet
• Premium plán ve Walletu kvůli přístupu k API tokenu

Lokální instalace

Z kořene repozitáře:

npm link

Pak bude bbwallet dostupný v PATH.

Bez linkování:

node ./bin/bbwallet.js --help

Autentizace

Autentizaci stačí nastavit jednou:

bbwallet auth login
bbwallet auth login --no-open

CLI otevře nastavení Wallet REST API a požádá Vás o vložení API tokenu:

• stránka nastavení: https://web.budgetbakers.com/settings/rest-api
• pokud nejste přihlášeni, Wallet Vás nejdřív přesměruje na login
• po vložení tokenu ho CLI ověří a uloží mimo repozitář

Cesta k uloženým přihlašovacím údajům:

• macOS: ~/Library/Application Support/bbwallet/credentials.json
• Linux: $XDG_CONFIG_HOME/bbwallet/credentials.json nebo ~/.config/bbwallet/credentials.json
• Windows: %APPDATA%\\bbwallet\\credentials.json

Další auth příkazy:

bbwallet auth status
bbwallet auth logout

auth status rozlišuje:

• validation_status: "valid" pro funkční token
• validation_status: "invalid" pro neplatné přihlašovací údaje
• validation_status: "unknown" pro dočasné chyby při ověřování, třeba rate limit
• validation_status: "not_configured" když úložiště přihlašovacích údajů ještě neexistuje

Příkazy

Výpisy zdrojů

bbwallet --json accounts list --all
bbwallet --json categories list --all
bbwallet --json budgets list
bbwallet --json goals list
bbwallet --json labels list
bbwallet --json standing-orders list
bbwallet --json record-rules list

Podporované výpisové zdroje:

accounts
categories
budgets
goals
labels
standing-orders
record-rules

Obecné flagy pro výpisové endpointy:

--limit <1-200>
--offset <number>
--max-pages <number>
--all
--id <id[,id2,...]>
--name <substring>
--name-exact <exact name>

Záznamy

bbwallet --json records list --from 2026-04-01 --to 2026-04-30
bbwallet --json records list --category-name Groceries --sort -recordDate
bbwallet --json records list --account-name Revolut --account-currency EUR --limit 20
bbwallet --json records get <record-id>
bbwallet --json records get-many --id rec_123,rec_456

Použití:

bbwallet records list [flags]
bbwallet records get <record-id>
bbwallet records get-many --id <id[,id2,...]>

Flagy pro záznamy:

--from YYYY-MM-DD
--to YYYY-MM-DD
--account-id <id>
--account-name <query>
--account-currency <currency code>
--category-id <id>
--category-name <query>
--label-id <id>
--label-name <query>
--note-contains <text>
--payee-contains <text>
--payer-contains <text>
--amount-gte <number>
--amount-lte <number>
--sort <+recordDate|-recordDate|+amount|-amount|+createdAt|-createdAt|+updatedAt|-updatedAt>
--limit <1-200>
--offset <number>
--max-pages <number>
--all

Překlad názvů na ID

bbwallet --json resolve account Revolut
bbwallet --json resolve account Revolut --currency-code EUR
bbwallet --json resolve category Groceries
bbwallet --json resolve label Work

Použití:

bbwallet resolve account <query> [--exact] [--currency-code <code>]
bbwallet resolve category <query> [--exact]
bbwallet resolve label <query> [--exact]

--exact vynutí přesnou shodu názvu. --currency-code je podporované jen pro resolve account a dává smysl hlavně u účtů se stejným názvem v různých měnách.

Využití API

bbwallet --json usage stats --period 30days
bbwallet --json usage stats --period 4weeks
bbwallet --json usage stats --period 6months

Vestavěné reporty

bbwallet --json report spending-by-category --from 2026-04-01 --to 2026-04-30 --top 10
bbwallet --json report by-account --from 2026-04-01 --to 2026-04-30 --top 10
bbwallet --json report top-counterparties --from 2026-04-01 --to 2026-04-30 --top 10
bbwallet --json report monthly-summary --from 2026-01-01 --to 2026-04-30 --max-pages 5

Použití:

bbwallet report spending-by-category --from YYYY-MM-DD --to YYYY-MM-DD [flags]
bbwallet report by-account --from YYYY-MM-DD --to YYYY-MM-DD [flags]
bbwallet report top-counterparties --from YYYY-MM-DD --to YYYY-MM-DD [flags]
bbwallet report monthly-summary --from YYYY-MM-DD --to YYYY-MM-DD [flags]

Tyhle reporty počítají agregace na klientovi nad endpointem /records.

Společná pravidla:

• --from a --to jsou povinné pro všechny reporty
• reporty podporují stejné filtry jako records list, včetně --account-name, --account-currency, --category-name, --label-name, --note-contains, --payee-contains, --payer-contains, --amount-gte, --amount-lte a --exact
• --max-pages je praktická brzda pro větší datasety nebo při práci pod rate limitem

Doplňkové flagy:

spending-by-category: --top <n>
by-account: --top <n>
top-counterparties: --top <n>
monthly-summary: bez --top

Poznámky k reportům:

• report by-account vrací i accountDisplayName, takže duplicitní názvy účtů jsou rozlišené třeba jako Revolut (EUR) a Revolut (CZK)
• report top-counterparties se u známých bankovních účtů pokouší převést číslo účtu zpátky na Wallet účet

JSON kontrakt

Spouštění příkazů vrací JSON. Úspěšná odpověď obsahuje:

• ok
• command
• data
• rate_limit
• sync
• pagination, pokud dává smysl

Chyby jdou na stderr a mají tenhle tvar:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded",
    "details": {
      "retry_after_seconds": 60
    }
  }
}

Exit kódy

• 0 úspěch
• 1 neočekávaná lokální nebo běhová chyba
• 2 neplatné flagy nebo nejednoznačné rozlišení názvu
• 3 auth nebo setup chyba
• 4 rate limit
• 5 probíhá initial sync ve Walletu
• 6 API nebo serverová chyba

--help (nebo spuštění bez příkazu) je v prostém textu a končí s 0.

Testy

npm test