xero-command-line

A command-line tool for the Xero API using PKCE OAuth. Authenticates via browser-based login — no client secret required. Supports multiple Xero organisations via named profiles.

Alpha (v0.0.7) — APIs may change.

Install

npm install -g @xeroapi/xero-command-line

Or try it without installing:

npx @xeroapi/xero-command-line <command>

From source

git clone https://github.com/XeroAPI/xero-command-line.git
cd xero-command-line
npm install
npm run build
npm link

Prerequisites

• Node.js >= 18
• A Xero OAuth 2.0 app at developer.xero.com (no client secret needed — PKCE handles authentication)
• Set the redirect URI on your OAuth 2.0 PKCE app to http://localhost:8742/callback

Setup

1. Create a profile with your Xero app's Client ID:

xero profile add my-company
# Prompts for Client ID

Or pass it inline:

xero profile add my-company --client-id YOUR_CLIENT_ID

2. Log in via the browser:

xero login

This opens your browser for Xero's OAuth consent flow. After you authorize, the CLI receives tokens via a local callback server. If your app is connected to multiple organisations, you'll be prompted to select one.

Tokens are encrypted (AES-256-GCM) and cached at ~/.config/xero-command-line/tokens.json. Tokens refresh automatically when expired.

Token storage

The CLI encrypts OAuth tokens at rest in ~/.config/xero-command-line/tokens.json. Where the encryption key is stored, from most to least secure:

1. OS keychain (default in auto mode) — macOS Keychain, Windows Credential Manager, or Linux Secret Service (GNOME Keyring / KWallet via D-Bus). Recommended on desktop systems. No encryption key file is written unless you opt in below.
2. XERO_TOKEN_PASSPHRASE — Derives the key with scrypt from your passphrase and a local salt file. The raw key is not stored on disk. Set the same value before xero login and every later command. Stronger than a file-stored key if you accept managing a secret env var.
3. XERO_KEYRING_FILE_BACKUP=1 (opt-in) — When the keychain accepts a new key, also writes a copy to ~/.config/xero-command-line/.encryption-key (mode 0600). If a later command cannot read the keychain (common on WSL, SSH, or headless Linux), the CLI reads this file instead. Off by default so macOS/Windows/Linux desktops keep the key keychain-only. Enable only when the keychain is installed but reads are unreliable.
4. XERO_KEY_STORAGE=file — Store the key only in .encryption-key (skip the keychain). Use when no secret service is available; weaker than keychain-only because any process running as your user can read the key file.

Variable	Values	Default
XERO_KEY_STORAGE	auto, keyring, file	auto
XERO_KEYRING_FILE_BACKUP	1, true, yes	off
XERO_TOKEN_PASSPHRASE	your passphrase	off

In auto mode without file backup, if the keychain is completely unavailable at login, the CLI still writes .encryption-key once so login can succeed — same as a file-only fallback for that session.

On Linux, WSL, or SSH, if login works once and later commands fail with an encryption-key error, the secret service was likely unavailable in that shell. The CLI does not delete tokens.json on decrypt errors.