核心用法
freshbooks-cli 是一款面向 FreshBooks 云会计平台的命令行工具，基于官方 @freshbooks/api SDK 构建。它通过 OAuth2 认证与 FreshBooks API 交互，提供完整的发票生命周期管理、客户 CRUD 操作及账单查询功能。
认证机制：采用 OAuth2 OOB（Out-of-Band）流程，--manual 标志强制浏览器授权后回拷授权码，令牌存储于 ~/.config/freshbooks-cli/config.json 并设置 0600 权限，支持自动刷新机制。
核心功能模块：
- 客户管理：
clients list/get/create/update，支持按组织名搜索，JSON 数据批量导入 - 发票管理：
invoices list/get/create/update/archive/share-link，完整支持多币种金额对象（{"amount": "string", "code": "USD"}） - 账单工作流：从客户创建到发票生成、分享链接的一站式自动化
显著优点：
1. 官方 SDK 背书：基于 @freshbooks/api 封装，API 兼容性与稳定性有保障
2. 开发者友好：纯 JSON 输出，管道友好（jq 集成），支持环境变量注入凭据
3. 安全设计：令牌文件权限严格控制（0600），自动刷新机制减少凭据暴露风险
4. 工作流封装：内置"客户-发票"完整业务链路示例，降低集成成本
潜在缺点与局限性：
1. GitHub Package Registry 依赖：需额外配置 .npmrc 指向私有 registry，增加安装复杂度
2. 手动授权流程：--manual 为强制要求，无法完全 headless 自动化部署
3. 无永久删除：FreshBooks API 限制，archive 仅设置 vis_state=1，数据清理需平台端操作
4. 金额类型限制：货币金额必须为字符串格式，禁止数值运算，易引发类型错误
适合人群：
- 需要批量处理发票的开发者/DevOps 工程师
- 自由职业者/小型 agency 的自动化财务集成需求
- 已有 FreshBooks 订阅、寻求 CLI 工作流替代手动 GUI 操作的技术用户
常规风险：
- 令牌泄露风险（尽管文件权限已限制）
- OAuth 回调 URI 配置不当导致的授权失败
- 生产环境误操作发票/客户数据（建议操作前二次确认）