xero-cli-bin

Xero Accounting API 命令行工具 - 透過 npx 直接使用

安裝

使用 Yarn (推薦)

# 全域安裝
yarn global add xero-cli-bin
xero-cli --version

# 或專案安裝
yarn add xero-cli-bin

使用 npm

# 全域安裝
npm install -g xero-cli-bin
xero-cli --version

使用 npx (無需安裝)

# 直接使用
npx xero-cli-bin --version
npx xero-cli-bin auth
npx xero-cli-bin invoices list

功能特點

• 🔐 OAuth2 PKCE 認證
• 📄 發票管理（查詢、取得）
• 👥 聯絡人管理
• 🏦 帳戶查詢
• 💰 付款記錄查詢
• 📊 貸項通知單查詢
• 🔄 Token 自動更新
• 🔒 加密儲存憑證

系統需求

• Node.js >= 14.0.0
• 支援平台：
  • Windows (x64, arm64)
  • macOS (x64, arm64)
  • Linux (x64, arm64)

使用說明

1. 認證

npx xero-cli-bin auth

首次使用需要進行 OAuth2 認證，會開啟瀏覽器引導您完成授權流程。

2. 查看狀態

npx xero-cli-bin status

3. 查詢發票

# 列出所有發票
npx xero-cli-bin invoices list

# 查詢已授權的應收發票
npx xero-cli-bin invoices list --type ACCREC --status AUTHORISED

# 條件查詢
npx xero-cli-bin invoices list --where "AmountDue>0"

# JSON 輸出
npx xero-cli-bin invoices list --json

4. 查詢聯絡人

# 列出客戶
npx xero-cli-bin contacts list --type customer

# 搜尋聯絡人
npx xero-cli-bin contacts list --search-term "Smith"

# 條件查詢
npx xero-cli-bin contacts list --where "Name.Contains('ABC')"

5. 查詢帳戶

npx xero-cli-bin accounts list

6. 查詢付款

npx xero-cli-bin payments list --type AR

環境變數

| 變數 | 說明 | 必填 | |------|------|------| | XERO_CLIENT_ID | Xero Client ID | ✅ | | XERO_REDIRECT_URI | Redirect URI | ❌ (預設：http://localhost:3456/callback) | | XERO_SCOPES | OAuth Scopes | ❌ |

常見命令

# 認證
npx xero-cli-bin auth
npx xero-cli-bin auth --client-id=xxx --port=4000

# 狀態
npx xero-cli-bin status --json

# 發票
npx xero-cli-bin invoices list --type ACCREC --status AUTHORISED
npx xero-cli-bin invoices get <invoice-uuid>

# 聯絡人
npx xero-cli-bin contacts list --type customer
npx xero-cli-bin contacts get <contact-uuid>

# 帳戶
npx xero-cli-bin accounts list

# 付款
npx xero-cli-bin payments list --type AR

# 貸項通知單
npx xero-cli-bin creditnotes list

# Token 管理
npx xero-cli-bin refresh
npx xero-cli-bin revoke

# 說明
npx xero-cli-bin --help
npx xero-cli-bin --llms

WHERE 子句語法

--where 參數接受 Xero API 的 SQL-like 查詢表達式：

# 基本運算子
npx xero-cli-bin invoices list --where "AmountDue>1000"
npx xero-cli-bin invoices list --where "Status=\"AUTHORISED\""

# 日期查詢
npx xero-cli-bin invoices list --where "Date>=DateTime(2024, 01, 01)"

# GUID 查詢
npx xero-cli-bin contacts list --where "Contact.ContactID=Guid('123e4567-e89b-12d3-a456-426614174000')"

# 部分匹配
npx xero-cli-bin contacts list --where "Name.Contains('ABC')"
npx xero-cli-bin contacts list --where "Name.StartsWith('Smith')"

# 邏輯運算
npx xero-cli-bin invoices list --where "Type=\"ACCREC\" AND AmountDue>0"
npx xero-cli-bin invoices list --where "AmountDue>1000 OR Total>5000"

排序與分頁

# 排序
npx xero-cli-bin invoices list --order-by Date --sort-direction DESC

# 分頁
npx xero-cli-bin invoices list --page 2 --page-size 50

jq 整合

# 統計總額
npx xero-cli-bin invoices list --json | jq '[.[].Total] | add'

# 依客戶分組
npx xero-cli-bin invoices list --json | \
  jq 'group_by(.Contact.Name) | .[] | {name: .[0].Contact.Name, total: (map(.AmountDue) | add)}'

# 匯出 CSV
npx xero-cli-bin invoices list --json | \
  jq -r '.[] | [.InvoiceNumber, .Contact.Name, .Total] | @csv'

安裝問題排除

下載失敗

如果安裝時下載失敗，請手動從 GitHub Releases 下載：

# 前往 https://github.com/mmhk/xero-cli/releases
# 下載對應平台的壓縮檔
# 解壓後將二進制文件放到 PATH 中

權限問題（macOS/Linux）

# npm
chmod +x $(npm root -g)/xero-cli-bin/bin/xero-cli

# yarn
chmod +x $(yarn global bin)/xero-cli

相關連結

• GitHub Repository
• Xero API 文件
• CHANGELOG
• 問題回報

License

MIT License