AllSquare CLI

The CLI needs Node.js 22 or newer.

npm install -g allsquare

The yarn command needs Yarn Classic (v1); newer Yarn versions removed global installs.

Check the installed version with allsquare --version.

allsquare auth login

1. Your browser opens the AllSquare sign-in and permission screen.
2. Review the requested access and approve it.
3. Return to the terminal. allsquare auth status confirms you are signed in and shows the access you granted.

allsquare auth login --no-browser prints the sign-in link instead of opening it. Sign-in finishes by redirecting to a temporary address on 127.0.0.1 of the machine running the CLI, so open the link in a browser on that same machine.

On a remote machine over SSH, find the port in the link's redirect_uri, forward it from another terminal, then open the link in your local browser before the login times out after five minutes:

ssh -L <port>:127.0.0.1:<port> you@your-server

Sign-in tokens are stored in your operating system's credential store (macOS Keychain, Windows Credential Manager, or a Linux Secret Service provider), not in plain files.

allsquare auth logout signs the CLI out. You can also disconnect it from Settings under Connected apps.

Commands print readable tables by default. Add --help to any command to see its options.

allsquare groups list
allsquare balances list
allsquare expenses list --group-id <group-id>

To add an expense, look up member IDs first, then name who shares it. The payer is always included.

allsquare groups members <group-id>
allsquare expenses create <group-id> \
  --description "Groceries" --amount 42.10 --currency USD \
  --split-with <member-id>

Settling up records which expenses are paid; it does not move money. Preview first, then settle:

allsquare settlements preview <group-id> --expense-id <expense-id>
allsquare settlements settle <group-id> --expense-id <expense-id>

Coding agents such as Claude Code, Codex, and Gemini CLI can run the CLI directly. Start by giving the agent the built-in guide:

allsquare agent-guide --json

It lists the rules and step-by-step workflows an agent should follow, including confirming each change with you before making it.

Machine-readable output

With --json, success and failure use a stable envelope:

{
  "ok": true,
  "data": { ... }
}

{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Expense not found",
    "retryable": false
  }
}

Exit codes:

• 0Success
• 2Invalid input or configuration; fix the command
• 3Sign-in or permission problem
• 4Conflict with current state, such as an expense that is already settled
• 5Temporary or service failure; safe to retry when retryable is true
• 6Not found; check the ID
• 1Unexpected failure

Safe retries

Pass --idempotency-key to a write and repeat the identical command if the result is unclear. Within 24 hours, a retry returns the original result with "replayed": true instead of writing twice; after that, the same key can write again. Keep every flag the same.

Creates that use a key also need --date (or --start-date for recurring expenses), so a retry after midnight still sends the identical request. The CLI rejects the command without it.

Deleting, settling up, and updating the CLI ask for confirmation; pass --yes when no one can answer the prompt.

Signing in grants read and write access by default.

• Read access lets the CLI view your groups, members, expenses, recurring expenses, settlements, balances, and spending summaries.
• Write access lets it create, edit, and delete expenses and recurring expenses, settle up, create groups, and add or invite members.

For read-only credentials, for example when you give an agent access to reporting only, use allsquare auth login --read-only. Write commands then fail instead of asking for more access.

allsquare update --check
allsquare update

allsquare update upgrades global npm, pnpm, Yarn, and Bun installations after you confirm. If it cannot run the upgrade itself, for example on Windows, it shows the exact command to run.

Every command and flag, plus the JSON output and error details, is documented in the package README on npm. Prefer to connect a chat assistant instead? See the AI assistant guide.