Xero Cli

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 

Setup

1. Get Xero Credentials

Users need a Xero Developer account with API credentials:

1. Go to developer.xero.com/app/manage 2. Create a Web App 3. Set redirect URI: http://localhost:5001/callback 4. 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 | Switch active organization |

Invoices

| Command | Description | |---------|-------------| | invoices list | List all invoices | | invoices list --status AUTHORISED | Filter by status | | invoices list --contact | Filter by contact | | invoices get | Get invoice details | | invoices create --contact --items '' | Create invoice | | invoices update --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 | 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 | 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 | Get details | | banktransactions create ... | Create transaction | | banktransactions attach | Attach file |

Types: SPEND, RECEIVE, RECEIVE-OVERPAYMENT, SPEND-OVERPAYMENT

Payments

| Command | Description | |---------|-------------| | payments list | List all payments | | payments list --invoice | Filter by invoice | | payments get | Get payment details | | payments create ... | Create payment | | payments delete | Void payment |

Allocations

| Command | Description | |---------|-------------| | allocations list-overpayments | List overpayments | | allocations list-prepayments | List prepayments | | allocations list-creditnotes | List credit notes | | allocations overpayment -o -i -a | Apply overpayment | | allocations prepayment -p -i -a | Apply prepayment | | allocations creditnote -c -i -a | 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 "" \
  --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  --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 "" \
  --account "" \
  --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 "" \
  --contact "" \
  --items '[{"description":"Payment","unitAmount":500,"accountCode":"200"}]'
2. Attach receipt
npx -y bun ${SKILL_DIR}/scripts/cli.ts banktransactions attach "" ./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 |

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.

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 "" \
  --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  --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 "" \
  --account "" \
  --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 "" \
  --contact "" \
  --items '[{"description":"Payment","unitAmount":500,"accountCode":"200"}]'
2. Attach receipt
npx -y bun ${SKILL_DIR}/scripts/cli.ts banktransactions attach "" ./receipt.pdf

1. Get Xero Credentials

Users need a Xero Developer account with API credentials:

1. Go to developer.xero.com/app/manage 2. Create a Web App 3. Set redirect URI: http://localhost:5001/callback 4. 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