freshbooks-cli
CLI tool for managing FreshBooks invoices, clients, and billing. Uses the official @freshbooks/api SDK.
Install
CODEBLOCK0
Requires .npmrc with @haseebuchiha:registry=https://npm.pkg.github.com for GitHub Package Registry.
Setup (once)
Authenticate with FreshBooks OAuth2. You must use the --manual flag (localhost redirect does not work with FreshBooks).
CODEBLOCK1
This opens the browser. Authorize, then copy the code from the page and paste it into the CLI. Tokens are stored at ~/.config/freshbooks-cli/config.json (0600 permissions) and auto-refresh before expiry.
Verify: INLINECODE5
Auth commands
- -
freshbooks auth login --client-id <id> --client-secret <secret> --manual -- authenticate via OAuth2 OOB flow - INLINECODE7 -- clear stored tokens and credentials
- INLINECODE8 -- show account ID, token expiry, and auth state
- INLINECODE9 -- manually refresh the access token
Clients commands
- -
freshbooks clients list [-p <page>] [--per-page <n>] [-s <search>] -- list clients, search by org name - INLINECODE11 -- get a single client by ID
- INLINECODE12 -- create a client
- INLINECODE13 -- create with full JSON payload
- INLINECODE14 -- update a client
Example: INLINECODE15
Invoices commands
- -
freshbooks invoices list [-p <page>] [--per-page <n>] -- list invoices - INLINECODE17 -- get a single invoice by ID
- INLINECODE18 -- create an invoice with line items
- INLINECODE19 -- create with full JSON payload
- INLINECODE20 -- update an invoice
- INLINECODE21 -- archive an invoice (no permanent delete in FreshBooks)
- INLINECODE22 -- get a shareable link for an invoice
Line items format
Lines are a JSON array. Each line has name, qty, and unitCost (money object):
CODEBLOCK2
Example (full invoice create):
CODEBLOCK3
Workflows
Onboard a new client and invoice them
- 1.
freshbooks clients create --fname "Name" --organization "Company" -- note the returned INLINECODE27 - INLINECODE28 -- create the invoice
- INLINECODE29 -- get shareable link
Look up billing for a client
- 1.
freshbooks clients list -s "company name" -- find the client ID - INLINECODE31 -- list all invoices (filter by client in output)
- INLINECODE32 -- get full invoice details
Notes
- - All output is JSON to stdout. Pipe to
jq for filtering: INLINECODE34 - Money values are
{"amount": "string", "code": "USD"}. The amount is always a string like "30000.00", never a number. Do not use parseFloat on money. - INLINECODE37 sets vis_state=1. FreshBooks does not support permanent deletion.
- Tokens auto-refresh. If refresh fails, re-run
freshbooks auth login --client-id <id> --client-secret <secret> --manual. - Client credentials can also be read from env vars
FRESHBOOKS_CLIENT_ID and FRESHBOOKS_CLIENT_SECRET (takes priority over stored config). - Always use
--manual for auth login. The localhost callback redirect URI does not work with FreshBooks. - Confirm with the user before creating invoices or modifying billing data.
freshbooks-cli
用于管理FreshBooks发票、客户和账单的CLI工具。使用官方@freshbooks/api SDK。
安装
bash
npm install -g @haseebuchiha/freshbooks-cli
需要包含@haseebuchiha:registry=https://npm.pkg.github.com的.npmrc文件，用于GitHub包注册表。
设置（一次性操作）
通过FreshBooks OAuth2进行身份验证。必须使用--manual标志（localhost重定向不适用于FreshBooks）。
bash
freshbooks auth login \
--client-id CLIENTID> \
--client-secret CLIENTSECRET> \
--manual
此操作会打开浏览器。授权后，从页面复制代码并粘贴到CLI中。令牌存储在~/.config/freshbooks-cli/config.json（权限为0600），并在过期前自动刷新。
验证：freshbooks auth status
认证命令
- - freshbooks auth login --client-id --client-secret --manual -- 通过OAuth2 OOB流程进行身份验证
- freshbooks auth logout -- 清除存储的令牌和凭证
- freshbooks auth status -- 显示账户ID、令牌过期时间和认证状态
- freshbooks auth refresh -- 手动刷新访问令牌
客户命令
- - freshbooks clients list [-p ] [--per-page ] [-s ] -- 列出客户，按组织名称搜索
- freshbooks clients get -- 按ID获取单个客户
- freshbooks clients create [--fname ] [--lname ] [--email ] [--organization ] -- 创建客户
- freshbooks clients create --data -- 使用完整JSON负载创建客户
- freshbooks clients update --data -- 更新客户
示例：freshbooks clients create --fname Taha --organization abcg.io
发票命令
- - freshbooks invoices list [-p ] [--per-page ] -- 列出发票
- freshbooks invoices get -- 按ID获取单个发票
- freshbooks invoices create --client-id [--lines ] -- 创建包含行项目的发票
- freshbooks invoices create --client-id --data -- 使用完整JSON负载创建发票
- freshbooks invoices update --data -- 更新发票
- freshbooks invoices archive -- 归档发票（FreshBooks不支持永久删除）
- freshbooks invoices share-link -- 获取发票的可分享链接
行项目格式
行项目是一个JSON数组。每个行项目包含name、qty和unitCost（金额对象）：
json
[
{name: Web服务, qty: 1, unitCost: {amount: 15000.00, code: USD}},
{name: 应用服务, qty: 1, unitCost: {amount: 15000.00, code: USD}}
]
示例（完整创建发票）：
bash
freshbooks invoices create --client-id 818183 \
--lines [{name:Web服务,qty:1,unitCost:{amount:15000.00,code:USD}},{name:应用服务,qty:1,unitCost:{amount:15000.00,code:USD}}]
工作流程
接入新客户并开具发票
- 1. freshbooks clients create --fname 姓名 --organization 公司 -- 记下返回的id
- freshbooks invoices create --client-id --lines [...] -- 创建发票
- freshbooks invoices share-link -- 获取可分享链接
查找客户的账单信息
- 1. freshbooks clients list -s 公司名称 -- 查找客户ID
- freshbooks invoices list -- 列出所有发票（在输出中按客户筛选）
- freshbooks invoices get -- 获取完整发票详情
注意事项
- - 所有输出均为JSON格式到标准输出。可通过管道传递给jq进行筛选：freshbooks clients list | jq .clients[].organization
- 金额值为{amount: string, code: USD}。金额始终为字符串，如30000.00，绝不是数字。不要对金额使用parseFloat。
- archive操作将visstate设置为1。FreshBooks不支持永久删除。
- 令牌会自动刷新。如果刷新失败，请重新运行freshbooks auth login --client-id --client-secret --manual。
- 客户端凭证也可以从环境变量FRESHBOOKSCLIENTID和FRESHBOOKSCLIENT_SECRET中读取（优先级高于存储的配置）。
- 认证登录时始终使用--manual标志。localhost回调重定向URI不适用于FreshBooks。
- 在创建发票或修改账单数据前，请先与用户确认。
