Xero Accounting Skill
Interact with Xero accounting software via CLI. Manage invoices, contacts, payments, bank transactions, and more. All commands output JSON for easy parsing.
Script Directory
Agent: Determine this SKILL.md file's directory as SKILL_DIR, then run commands with:
npx -y bun ${SKILL_DIR}/scripts/cli.ts <command>
Setup
1. Get Xero Credentials
Users need a Xero Developer account with API credentials:
- Go to developer.xero.com/app/manage
- Create a Web App
- Set redirect URI:
http://localhost:5001/callback
- Copy the Client ID and Client Secret
Note: If you see a scopes configuration page, add: openid, offline_access, accounting.contacts, accounting.settings, accounting.invoices, accounting.payments, accounting.banktransactions, accounting.attachments. If no scopes page is shown, that's fine - scopes are requested during OAuth.
Agent note: If credentials are missing, ask the user for their Client ID and Secret.
2. Configure OpenClaw
Add credentials to openclaw.json:
{
"skills": {
"xero": {
"env": {
"XERO_CLIENT_ID": "your_client_id",
"XERO_CLIENT_SECRET": "your_client_secret"
}
}
}
}
3. Authenticate
npx -y bun ${SKILL_DIR}/scripts/cli.ts auth login
This opens a browser for OAuth. Once complete, verify with:
npx -y bun ${SKILL_DIR}/scripts/cli.ts auth status
Quick Reference
Command prefix: npx -y bun ${SKILL_DIR}/scripts/cli.ts
Authentication
| Command | Description |
|---|
auth login | Start OAuth flow (opens browser) |
auth status | Check authentication status |
auth logout | Clear stored credentials |
Organizations
| Command | Description |
|---|
tenants list | List connected Xero organizations |
tenants select <id> | Switch active organization |
Invoices
| Command | Description |
|---|
invoices list | List all invoices |
invoices list --status AUTHORISED | Filter by status |
invoices list --contact <id> | Filter by contact |
invoices get <id> | Get invoice details |
invoices create --contact <id> --items '<json>' | Create invoice |
invoices update <id> --status AUTHORISED | Update status |
Statuses: DRAFT, AUTHORISED, PAID, VOIDED
Types: ACCREC (sales), ACCPAY (bills)
Contacts
| Command | Description |
|---|
contacts list | List all contacts |
contacts list --search "name" | Search by name |
contacts list --customers | Only customers |
contacts list --suppliers | Only suppliers |
contacts get <id> | Get contact details |
contacts create --name "X" --email "Y" | Create contact |
Accounts
| Command | Description |
|---|
accounts list | List all accounts |
accounts list --type REVENUE | Filter by type |
accounts list --class EXPENSE | Filter by class |
accounts get <id> | Get account details |
Types: BANK, REVENUE, EXPENSE, FIXED, CURRENT, LIABILITY, EQUITY, etc.
Classes: ASSET, EQUITY, EXPENSE, LIABILITY, REVENUE
Bank Transactions
| Command | Description |
|---|
banktransactions list | List all transactions |
banktransactions list --type SPEND | Filter by type |
banktransactions get <id> | Get details |
banktransactions create ... | Create transaction |
banktransactions attach <id> <file> | Attach file |
Types: SPEND, RECEIVE, RECEIVE-OVERPAYMENT, SPEND-OVERPAYMENT
Payments
| Command | Description |
|---|
payments list | List all payments |
payments list --invoice <id> | Filter by invoice |
payments get <id> | Get payment details |
payments create ... | Create payment |
payments delete <id> | Void payment |
Allocations
| Command | Description |
|---|
allocations list-overpayments | List overpayments |
allocations list-prepayments | List prepayments |
allocations list-creditnotes | List credit notes |
allocations overpayment -o <id> -i <inv> -a <amt> | Apply overpayment |
allocations prepayment -p <id> -i <inv> -a <amt> | Apply prepayment |
allocations creditnote -c <id> -i <inv> -a <amt> | Apply credit note |
Examples
Create an Invoice
# 1. Find the contact
npx -y bun ${SKILL_DIR}/scripts/cli.ts contacts list --search "Acme"
# 2. Get revenue account codes
npx -y bun ${SKILL_DIR}/scripts/cli.ts accounts list --type REVENUE
# 3. Create the invoice
npx -y bun ${SKILL_DIR}/scripts/cli.ts invoices create \
--contact "<contact-id>" \
--items '[{"description":"Consulting","quantity":10,"unitAmount":150,"accountCode":"200"}]' \
--reference "INV-001"
# 4. Authorize when ready
npx -y bun ${SKILL_DIR}/scripts/cli.ts invoices update <invoice-id> --status AUTHORISED
Record a Payment
# 1. Get bank account ID
npx -y bun ${SKILL_DIR}/scripts/cli.ts accounts list --type BANK
# 2. Create payment (marks invoice as paid)
npx -y bun ${SKILL_DIR}/scripts/cli.ts payments create \
--invoice "<invoice-id>" \
--account "<bank-account-id>" \
--amount 500.00 \
--reconciled
Create a Contact
npx -y bun ${SKILL_DIR}/scripts/cli.ts contacts create \
--name "Acme Corporation" \
--email "billing@acme.com" \
--customer
Record Bank Transaction with Receipt
# 1. Create transaction
npx -y bun ${SKILL_DIR}/scripts/cli.ts banktransactions create \
--type RECEIVE \
--bank-account "<bank-id>" \
--contact "<contact-id>" \
--items '[{"description":"Payment","unitAmount":500,"accountCode":"200"}]'
# 2. Attach receipt
npx -y bun ${SKILL_DIR}/scripts/cli.ts banktransactions attach "<transaction-id>" ./receipt.pdf
Error Handling
Errors return JSON:
{"error": "Not authenticated. Run auth login"}
Common errors:
| Error | Solution |
|---|
| Not authenticated | Run auth login |
| Token expired | Run auth login again |
| No organization selected | Run tenants list then tenants select <id> |
Security Notes
Token Storage: OAuth tokens are saved to data/tokens.json in the working directory. This file contains sensitive access/refresh tokens - treat it as you would other credentials.
Environment Variables: The skill reads XERO_CLIENT_ID and XERO_CLIENT_SECRET from environment (set via OpenClaw config). Optional: XERO_REDIRECT_URI (default: http://localhost:5001/callback) and XERO_SCOPES.
Source Code: All skill code is bundled in the scripts/ directory for inspection. Review before granting access to production Xero organizations.
