xero-cli

name

xero-cli

description

Use when reading Xero accounting data from the command line or scripts — listing/looking up contacts, invoices, payments, bank transactions, manual journals; running reports (Trial Balance, Balance Sheet, P&L, BankSummary, Aged Receivables); downloading invoice PDFs or attachments; or managing the Xero OAuth2 connection (authorize, refresh, and verify you are connected to the correct organisation, not a trial/wrong tenant). Generic over any Xero org.

xero-cli

A small, dependency-light swiss-army CLI + Python client over the Xero accounting API, built for catch-up bookkeeping and audit reconstruction — bulk reads, range-filtered extraction, report pulls, PDF/attachment download — not for live transactional posting.

Core principle: the most expensive Xero auth failure is silently authorizing against the wrong organisation (a trial org, a different company file). This tool makes "which org am I actually talking to?" a first-class, enforced check.

When to use

• "Pull FY18-19 bank transactions for HSBC Current from Xero"
• "Run the Trial Balance / Balance Sheet / P&L / BankSummary as at a date"
• "Look up a contact / invoice / payment"
• "Download invoice PDFs for the audit archive"
• The Xero connection broke / "do our API keys still work?" → xero auth status
• Re-authorizing after a subscription lapse or revoked token → xero auth url + exchange

Not for: writing/posting transactions as a system of record (use the accounting ERP for that); the Xero Journals endpoint and Reports/BankStatement are unavailable under the post-2026-03 granular-scope regime (see references/auth.md).

Setup (once per deployment)

$XERO_HOME (default ~/.config/xero-cli) holds config.json — secrets, never committed. Copy scripts/config.example.json and fill in:

{
  "client_id": "...", "client_secret": "...",
  "redirect_uri": "http://localhost:1234/callback",
  "tokens_path": "/abs/path/to/tokens.json",
  "expected_tenant_id": "....-....", "expected_tenant_name": "ACME LTD"
}

tokens_path can point at an existing token store, so the CLI is a drop-in over scripts that already manage tokens. expected_tenant_id arms the wrong-org guard.

Quick reference

Command	Does
xero auth status	Live /connections + active org + wrong-org/TRIAL guard (exit 1 on mismatch)
xero auth url	Build the PKCE authorize URL; writes pending_auth.json
xero auth exchange '<redirect-url>'	Finish OAuth; selects + pins the expected org
xero auth refresh	Force a token refresh
xero whoami	Org identity + financial-year end
xero ratecheck	Remaining minute/day/app quota (one cheap call)
xero get <Endpoint> [--where W] [--order O] [--all]	Generic GET; --all paginates
xero report <Name> [--date D | --from D --to D]	Reports/
xero pdf <InvoiceID> <out.pdf>	Download an invoice PDF

Reads guard the tenant automatically; --force bypasses (rarely correct).

The re-auth flow (recover a broken / wrong-org connection)

1. xero auth url → open the URL logged into Xero.
2. Select the correct organisation (the whole point — a wrong pick is how you end up on a trial org). Untick any others.
3. Browser fails to load …/callback?code=… (no listener — expected). Copy the full address-bar URL.
4. xero auth exchange '<that-url>' → confirms tenants, pins the expected one.
5. xero auth status → must print Match: ✓ OK and a non-TRIAL class.

Programmatic use

import sys; sys.path.insert(0, ".../scripts")
from xero_client import XeroClient, bank_txns_for_fy
api = XeroClient()              # auto-refresh; reads $XERO_HOME/config.json
api.assert_tenant()            # refuse to run against the wrong org
txns = bank_txns_for_fy(api, "FY18-19", "<bank-account-id>")
tb = api.get("Reports/TrialBalance", {"date": "2026-03-31"})

See references/auth.md (OAuth2/PKCE, token lifecycle, multi-tenant, scope regime, the wrong-org trap) and references/api.md (endpoints, where range filters, reports, rate limits, FY helpers). Add commands/scripts per CONTRIBUTING.md.