freshbooks-cli

freshbooks-cli 是一款基于官方 FreshBooks API SDK 构建的命令行工具，专为需要自动化财务管理流程的开发者和企业设计。通过简洁的 CLI 界面，用户可完成 OAuth2 认证、客户管理、发票创建与维护等核心财务操作，所有数据以 JSON 格式输出，便于与现有 DevOps 工具链集成。

核心用法围绕三大模块展开：认证模块支持手动 OAuth2 流程，令牌自动存储于本地配置文件并支持自动刷新；客户管理模块提供列表查询、搜索、创建和更新功能，支持通过 JSON 数据批量操作；发票管理模块涵盖创建、更新、归档及分享链接生成，特别支持复杂的行项目（Line Items）配置，满足专业计费需求。工具设计遵循 Unix 哲学，所有输出均可通过管道与 jq 等工具结合使用，实现高级数据处理和自动化脚本编写。

显著优点包括：采用纯文档型架构，本身无代码执行风险，安全性高；直接对接官方 FreshBooks API，数据交互可靠；支持环境变量注入敏感凭证，避免命令行历史泄露；自动化的令牌刷新机制减少了手动维护成本；JSON 输出格式标准化，便于与 CI/CD 流程或内部系统集成。

潜在局限性主要体现在：来源为个人开发者（T3 级），npm 包托管于 GitHub Package Registry，需额外配置 .npmrc 且存在供应链验证需求；OAuth 认证必须使用 --manual 模式，无法使用本地回调，交互流程相对繁琐；FreshBooks 平台本身不支持发票永久删除，仅提供归档功能；Money 对象采用字符串格式，需特别注意避免浮点数精度问题。

该工具最适合以下群体：使用 FreshBooks 作为财务后台的 SaaS 企业技术团队、需要将发票生成集成到内部工作流的开发者、追求命令行效率的财务人员，以及希望实现客户管理和计费自动化的中小型工作室。

使用风险方面，主要需关注 OAuth 凭证的安全管理，建议优先使用环境变量而非命令行参数传递敏感信息；定期验证 npm 包来源完整性，防范供应链攻击；确保配置文件 ~/.config/freshbooks-cli/config.json 保持 0600 权限；在执行创建发票或修改账单等关键操作前，务必进行二次确认，避免误操作导致财务数据错误。