AllSquare CLI

Agent-friendly command-line access to AllSquare through the public /api/v1 HTTP API.

Status

Beta. Commands, the JSON envelope, error codes, and exit codes are intended to stay compatible; new fields and commands will be added. Breaking changes, if needed, will come in a minor version with release notes.

Requirements

• Node.js 22 or newer
• An AllSquare account

Install

npm install -g allsquare
allsquare auth login

allsquare update upgrades a global npm, pnpm, Yarn, or Bun installation.

Current commands

allsquare --help
allsquare --version
allsquare agent-guide [--json]
allsquare update --check [--json]
allsquare update [--yes] [--json]
allsquare auth login
allsquare auth login --read-only
allsquare auth login --no-browser
allsquare auth status
allsquare auth refresh
allsquare auth logout
allsquare groups list
allsquare groups members <group-id>
allsquare groups create --name TEXT --currency CODE [--member-email EMAIL]
allsquare groups add-member <group-id> --email EMAIL
allsquare balances list [--currency USD]
allsquare balances show <group-id> [--currency USD]
allsquare expenses list [--group-id ID] [--query TEXT] [--from YYYY-MM-DD] [--to YYYY-MM-DD]
allsquare expenses list [--paid-by-id MEMBER_ID] [--is-recurring true|false] [--is-settled true|false]
allsquare expenses list [--limit 20] [--cursor CURSOR]
allsquare expenses get <expense-id>
allsquare expenses create <group-id> --description TEXT --amount DECIMAL --currency CODE
allsquare expenses create <group-id> [--paid-by-id ID] [--split-with ID] [--split-type amount|percentage|exact]
allsquare expenses create <group-id> [--percentage-split ID=PERCENT] [--exact-split ID=AMOUNT] [--date YYYY-MM-DD]
allsquare expenses update <expense-id> [--description TEXT] [--amount DECIMAL] [--currency CODE]
allsquare expenses update <expense-id> [--paid-by-id ID] [--split-with ID] [--split-type amount|percentage|exact]
allsquare expenses delete <expense-id> [--yes]
allsquare recurring-expenses list [--group-id ID]
allsquare recurring-expenses get <recurring-expense-id>
allsquare recurring-expenses create <group-id> --description TEXT --amount DECIMAL --currency CODE --frequency FREQUENCY
allsquare recurring-expenses create <group-id> [--start-date YYYY-MM-DD] [--paid-by-id ID] [--split-with ID]
allsquare recurring-expenses update <recurring-expense-id> [--description TEXT] [--amount DECIMAL] [--frequency FREQUENCY]
allsquare recurring-expenses update <recurring-expense-id> [--paid-by-id ID] [--split-with ID] [--split-type amount|percentage|exact]
allsquare recurring-expenses pause <recurring-expense-id>
allsquare recurring-expenses resume <recurring-expense-id>
allsquare recurring-expenses delete <recurring-expense-id> [--yes]
allsquare settlements list [--group-id ID] [--limit 20]
allsquare settlements preview <group-id> --expense-id ID [--expense-id ID] [--currency USD]
allsquare settlements settle <group-id> --expense-id ID [--expense-id ID] [--currency USD] [--yes]
allsquare spend-summary show [--group-id ID] [--from YYYY-MM-DD] [--to YYYY-MM-DD]
allsquare spend-summary show [--query TEXT] [--currency USD]
allsquare config show
allsquare config show --json

Add --json to any leaf command for machine-readable output. Login opens the system browser by default and completes through an ephemeral loopback callback. Use --no-browser to print the authorization URL without opening it.

Each CLI installation registers its own OAuth public client. Authorization uses PKCE, access tokens refresh automatically shortly before expiry, and refreshes are serialized across concurrent processes so agents cannot accidentally reuse a rotated refresh token. Plain auth login requests the CLI's normal read and write access in one consent flow. Use auth login --read-only to request only read access; write commands then fail with AUTH_REQUIRED rather than asking for more access. If a write command runs with no session at all from an interactive terminal, the CLI opens consent, waits for approval, then continues that same command. With --json or without a terminal it fails immediately with AUTH_REQUIRED (exit 3) so scripts and agents never wait on a browser. The older auth login --write flag remains accepted as an alias for the default; it is not required. Logging in again, including with --read-only, revokes the previous session's tokens; if that revocation cannot be confirmed, the login still succeeds and reports replacedSessionRevocation: "unconfirmed".

Refresh tokens are stored in the operating system credential vault (macOS Keychain, Windows Credential Manager, or a Linux Secret Service provider). Linux installations therefore need a working Secret Service implementation such as GNOME Keyring, KWallet, or KeePassXC. Non-secret client registration metadata is stored in the OS-standard application config directory with private permissions.

The default profile retains its existing keychain account. Setting ALLSQUARE_CONFIG_DIR creates a separate credential namespace for that folder, even when it targets the same API URL. A custom-folder profile does not read or move credentials stored under the old unscoped account name; log in separately in that profile if it previously relied on those credentials. Log out of a custom-folder profile before deleting its folder; deleting the folder alone does not remove its operating-system credential entry.

The CLI targets https://allsquare.app/api/v1 by default. Set ALLSQUARE_API_URL to use another deployment. Plain HTTP is accepted only for loopback URLs such as http://localhost:3000/api/v1.

Successful JSON output uses { "ok": true, "data": ... }. When a write reuses an idempotency key the server has already completed, the output adds "replayed": true (human output prints a note on stderr): nothing new was written, and data is the original result, which may describe a resource that has since changed or been deleted. The server keeps idempotency keys for 24 hours; after that, the same key can write again. Expected failures use { "ok": false, "error": { "code": ..., "message": ..., "retryable": ... } } on stderr and exit nonzero, including argument-parser failures. Every error includes retryable: true only when repeating the same command can succeed unchanged (rate limits, service or network failures, temporary login-service errors, a busy session refresh, or IN_PROGRESS while the same idempotent write is still running); retry writes with the same --idempotency-key. Error codes use one style (INVALID_ARGUMENT, AUTH_REQUIRED, FORBIDDEN, NOT_FOUND, CONFLICT, RATE_LIMITED, SERVICE_UNAVAILABLE, NETWORK_ERROR, ...); the server's own code is kept in details.apiCode. A group that does not exist returns FORBIDDEN, the same as one you cannot access. Exit codes are 0 for success, 2 for invalid input or configuration, 3 for authentication or permission, 4 for conflicts, 5 for temporary or service failures, and 6 for not found. Unexpected failures may exit 1. allsquare agent-guide --json lists every code.

auth logout always tries to remove local credentials even if the OAuth server cannot be reached. Its JSON result includes revocation (confirmed, unconfirmed, or not_needed). An unconfirmed result means the token may remain valid on the server; revoke the CLI connection in AllSquare settings if you need immediate server-side invalidation.

Agent use

Agents should begin with allsquare agent-guide --json. The guide is a versioned, machine-readable operating contract covering resource discovery, pagination, least-privilege authorization, write confirmation, idempotent retries, deletion, settlement, Venmo handoff, and the CLI output contract. The same content is available for humans with allsquare agent-guide.

The guide supplements safeguards enforced by the CLI. In particular, --yes means the calling agent has already obtained the required user confirmation; it does not grant permission on its own. Agents must preview settlements, render any returned Venmo links, avoid claiming that AllSquare completed or verified an external Venmo transaction, and record only the expense IDs the user selected.

allsquare update --check compares the installed version with the npm latest release without changing the installation. allsquare update can update recognized npm, pnpm, Yarn, or Bun global installations after an interactive confirmation; agents and other non-interactive callers must pass --yes. Source checkouts, local project dependencies, ephemeral invocations, and ambiguous installations are never modified automatically. The command returns installation-specific guidance instead. JSON execution captures package-manager output so the final success or error envelope remains machine-readable.

Group creation requires an explicit default currency. Repeat --member-email to add existing accounts or invite up to 20 initial members. groups add-member uses the same add-or-invite behavior for one address. These operations can send email; JSON output reports whether the membership or invitation was created and whether its notification was delivered. Both writes are idempotent, and --idempotency-key is available when retrying the same logical request.

Settlement preview is non-mutating and works with read-only authorization. It accepts up to 100 repeated --expense-id flags and shows the payments that a settlement would create without recording the settlement.

Settlement execution requires write authorization and always previews the exact expense IDs before recording anything. Interactive confirmation defaults to “no”; agents, JSON callers, and other non-interactive sessions must pass --yes. The confirmed request is idempotent, and --idempotency-key can be reused when retrying the same logical settlement: if the first attempt succeeded but its response was lost, the retry returns the original settlement with "replayed": true even though the preview now reports the expenses as settled. expenses delete and recurring-expenses delete behave the same way: a retry with the original --idempotency-key returns the original deletion even though the item is already gone. Recording a settlement marks the selected expenses settled; it does not transfer money.

Expense creation requires an explicit currency: USD, CAD, EUR, or GBP. Write commands need a session with write access; see the login notes above for when the CLI can prompt for one. --split-type amount means split equally between the payer and each --split-with member; the payer is always included. In a two-person group, omitting --split-with splits with the other member (as the web app does); larger groups must name at least one member besides the payer. Percentage and exact modes accept repeated MEMBER_ID=VALUE allocation flags, validate their totals locally, and include every named member even if it is not repeated in --split-with. --date defaults to today in your local time zone. A retry with --idempotency-key must be the identical command: the same flags and values, including --currency; otherwise the server rejects it as a different request. Creates that use --idempotency-key also require --date (or --start-date for recurring expenses), so a retry after midnight still sends the identical request. The order of repeated flags such as --split-with or --expense-id does not matter. The CLI generates an idempotency key automatically; pass --idempotency-key only when retrying the same logical creation across separate invocations.

Expense updates are partial, except that changing a split requires --split-type plus the complete replacement participant list. Interactive deletion displays the current expense and defaults to “no.” Agents and JSON callers must pass --yes; deletion still reads the exact target before sending the confirmed, idempotent delete request.

Recurring-expense writes use the same participant, split, amount, and idempotency safeguards. Frequencies are weekly, biweekly, monthly, or yearly. Pausing keeps generated history and stops future generation; resuming continues from the next scheduled date without backfilling the paused period. Recurring deletion is permanent, displays the exact template first for interactive users, and requires --yes for agents and JSON callers. Deleting a template stops future expenses but keeps the ones it already created. A template whose start date is today or earlier creates its first expense immediately and returns its ID as immediateExpenseId (null when only scheduled). Updates cannot change the next date or the currency; delete and recreate the template instead.

Development

The CLI is a standalone package inside the AllSquare repository. It does not import application or server modules from the repository root.

cd cli
pnpm install
pnpm check

Before packaging from this repository, install both the root and cli/ dependencies, then run pnpm --dir cli run prepack. That gate runs the CLI checks and compares its schemas with the generated v1 API contract. The CI workflow runs both test suites on each push and pull request.