Quick start

Spendly CLI lets you track expenses and manage account balances and cycles from your terminal using the same data as Spendly Web.

The initial 0.1.2 release is available on npm for macOS. Production authentication and read-only use through the Spendly skill in Codex have been verified. Broader production workflows remain subject to ongoing validation.

Install

You'll need Node.js 22 or newer and a Spendly account. macOS is the currently verified platform; Linux verification is planned, and Windows is not supported in the initial release. Install only on a computer you trust. Run this in your terminal:

npm install --global spendly
spendly --version

This makes the spendly command available in your terminal.

To install the exact initial version, use npm install --global spendly@0.1.2. Spendly will continue with 0.x releases until real usage proves the CLI contract is ready for 1.0.0.

Sign in

Open Spendly Web and finish setting up your account if you haven't already. Then run:

spendly auth login

Complete sign-in in the browser, then return to your terminal. To check your session:

spendly auth status

Authorization lasts for at most 30 days before browser sign-in is required again. Sign out and remove the locally stored session with:

spendly auth logout

Choose how to use Spendly

Use an AI agent

Continue to AI agents to install the skill for Codex or Claude Code. Then ask things like "Show my account balances" or "Record 18.75 for lunch today." You can go straight there without learning the commands below.

Try the CLI yourself

Open the guided command launcher:

spendly --interactive

Use the arrow keys or type to search, then press Enter. Guided commands use single-choice selectors for Spendly records, checkbox-style selectors for tags and filters, and a preview before saving. Press Escape or Ctrl-C to cancel without making a change. › marks the focused choice. In date inputs, brackets mark the active segment, for example [2026]-09-15; use Left/Right to change the segment and Up/Down to change its value.

For a screen reader or a terminal that does not handle cursor redraws well, use static numbered prompts:

spendly --interactive --accessible

You can also set ACCESSIBLE=1. This mode uses numbered single-choice inputs, comma-separated checkbox selections, plain yes/no confirmations, and no ANSI cursor movement. Spendly automatically selects it when TERM=dumb. Color is never required to understand focus, warnings, or errors.

See your current currency and cycle, account balances, and spending summary:

spendly context
spendly accounts list
spendly summary --current

Preview an expense without saving it:

spendly expenses add --interactive --dry-run

The guided form asks for the amount, date, description, category, account, and tags. The amount prompt includes the currency configured during onboarding, for example Expense amount (INR). To record the expense, run the same command without --dry-run, review the preview, and confirm it. Values already supplied as flags are kept. The category list contains visible categories from the cycle covering the selected date, followed by an explicit Uncategorized choice. Automatic history inference remains available to scripts that omit a category, but it is not exposed as a guided choice.

Install local command and global-option completion by generating the script for your shell and following that shell's normal sourcing setup:

spendly completion zsh
spendly completion bash
spendly completion fish

Find your next command

spendly --help
spendly expenses --help
spendly expenses add --help

Explore expenses, accounts, cycles, categories, or tags. If something fails, see Troubleshooting.