核心用法
xero-command-line 是 Xero 官方提供的命令行工具，基于 PKCE OAuth 认证，支持对 Xero 会计 API 的完整操作。主要功能涵盖：联系人管理、发票/报价单/贷项通知单处理、付款记录、银行交易、手动日记账、追踪类别、多币种、税率查询及财务报表生成。
认证流程：首次使用需执行 xero login 完成浏览器 OAuth 授权，令牌加密存储于 ~/.config/xero-command-line/tokens.json。支持多配置文件（profile）管理，可在同一客户端切换不同组织或 OAuth 应用。
数据操作模式：
- 读取：列表查询（支持分页、搜索、过滤）与详情获取
- 写入：单行内联创建或 JSON 文件批量创建（推荐多行项目场景）
- 输出格式：默认表格、JSON、CSV、TOON（Token Oriented Object Notation，LLM 友好格式）
关键安全机制：
- 执行任何写操作前必须运行
xero org details确认目标组织 - 支持
-p <profile>显式指定配置，避免环境变量静默覆盖 - 令牌加密依赖系统密钥环（Linux: GNOME Keyring），WSL/SSH 环境提供降级文件存储方案
显著优点
1. 官方维护：由 XeroAPI 团队直接开发，API 兼容性有保障
2. 完整功能覆盖：涵盖 Xero 会计 API 的全部核心资源类型
3. 灵活认证：PKCE 流程无需客户端密钥，降低凭证泄露风险
4. 多环境适配：提供密钥环、文件备份、密码派生等多种令牌存储策略
5. 细粒度权限：支持 OAuth 作用域精确控制（如只读模式）
6. LLM 优化：内置 TOON 输出格式，显著降低 token 消耗
潜在缺点与局限性
1. 认证复杂性：浏览器 OAuth 流程无法全自动完成，需用户介入
2. Linux 依赖：密钥环依赖 D-Bus/GNOME，无头环境需额外配置
3. 作用域迁移：2026 年 3 月起 Xero 废弃 broad scopes，旧应用需显式指定作用域
4. 更新限制：仅草稿状态发票/报价单/贷项通知单可更新
5. 手动日记账约束：必须成对借贷分录，无法单行内联创建
6. GUID 依赖：大多数操作需先查询获取 Xero GUID，无法直接使用人类可读标识
适合人群
- 中小企业财务团队需批量处理发票、付款、银行对账
- 开发者构建与 Xero 集成的自动化工作流（CI/CD、数据同步）
- 会计师/簿记员需快速提取报表数据（试算表、损益表、资产负债表）
- 多组织管理团队需在同一终端切换不同 Xero 账套
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| 组织误操作 | 写入数据至错误组织 | 强制 `xero org details` 确认 + 显式 `-p` 参数 |
| 令牌泄露 | 加密密钥存储不当 | 优先使用系统密钥环，避免 `XERO_KEY_STORAGE=file` |
| 数据覆盖 | 更新非草稿状态单据失败 | 操作前查询状态，仅对 DRAFT 执行更新 |
| 作用域不足 | API 调用因权限失败 | 登录时显式指定 `--scope` 匹配应用配置 |
| 环境变量干扰 | `XERO_PROFILE` 等变量静默改变行为 | 执行前检查环境变量，必要时清空 |
总体评估：该工具功能完整、官方背书，适合技术型财务用户和开发者。但认证流程和 Linux 密钥环配置存在门槛，多组织场景需特别注意身份验证步骤以防数据误写。