CLI

The walletguide CLI: every REST route as a command, browser sign-in or an API key, tables in a terminal and JSON in a pipe.

npx walletguide wallets list

Or keep it around:

npm install -g walletguide

Node 22 or newer.

Signing in

walletguide login

A browser opens, you approve, and the tokens land in ~/.walletguide/config.json with mode 0600. The session refreshes itself, so this is a once-per-machine thing. You can untick write access on the consent screen for a read-only session.

For CI, use a key:

walletguide login --api-key wg_…             # store it
echo "$WG_KEY" | walletguide login --api-key -   # or from stdin
WALLETGUIDE_API_KEY=wg_… walletguide assets list  # or not at all

walletguide whoami says which credential is in play, what it can reach and when it expires.

Wallets

A key belongs to one wallet and the CLI works that out itself. An OAuth session can reach several:

walletguide wallets list
walletguide wallets use              # prompts
walletguide wallets use <id>         # or name it
walletguide --wallet <id> assets list   # or override once

Commands

<resource> <action>, mirroring the routes. walletguide --help lists the resources and walletguide assets --help lists what you can do to them.

walletguide assets list
walletguide transactions list --from 2026-01-01 --limit 50
walletguide categories create --name Travel --type variableExpenses
walletguide data netWorthTimeSeries --period ytd

Anything with a request body takes --from-json <file> (or - for stdin), and its top-level fields also have flags. Flags win over the file, so a template plus one override works:

walletguide transactions create --from-json ./template.json --description Lunch

Output

A terminal gets a table, a pipe gets JSON. --json and --table override that, and --columns picks the columns.

walletguide assets list                          # table
walletguide assets list | jq '.[].name'          # json
walletguide assets list --columns id,name,value

Profiles

One per environment or account, all in ~/.walletguide/config.json.

walletguide --profile staging login --base-url https://staging-api.walletguide.com
walletguide --profile staging wallets list

Variable	What it does
`WALLETGUIDE_API_KEY`	Use this key, ignoring what is stored
`WALLETGUIDE_BASE_URL`	Point at another api
`WALLETGUIDE_WALLET_ID`	The wallet to act on

Recipes

Export a year of transactions:

walletguide transactions list --from 2026-01-01 --to 2026-12-31 --limit 1000 --json \
  > transactions-2026.json

A monthly number, on a schedule. Ask the slice, not the rows:

walletguide data profitLoss --period lastMonth --json \
  | jq '{income: .totalIncome, expenses: .totalExpenses}'

What a category usually costs:

walletguide data categoryAverages --period 1year --json \
  | jq -r '.[] | "\(.categoryName)\t\(.average)"' | sort -k2 -nr | head -10

Create from a file, or from a pipe:

walletguide categories create --from-json ./category.json
jq -n '{name:"Travel",type:"variableExpenses"}' | walletguide categories create --from-json -

The same body many times — flags override the file, so one template covers a batch:

for name in Groceries Transport Utilities; do
  walletguide categories create --from-json ./template.json --name "$name"
done

In CI, with no login and no config file:

- name: Export last month
  env:
    WALLETGUIDE_API_KEY: ${{ secrets.WALLETGUIDE_API_KEY }}
  run: npx walletguide data profitLoss --period lastMonth --json > pl.json

Output is JSON automatically when stdout is not a terminal, so --json there is belt and braces.

When something fails

walletguide whoami first: it names the credential, the wallet and the token's expiry. A 401 comes back saying which of three things went wrong — an opaque token, an audience minted for /mcp rather than the API, or a revoked grant — so read the whole message before signing in again. See errors.