freshbooks-cli

# freshbooks-cli

CLI tool for managing FreshBooks invoices, clients, and billing. Uses the official `@freshbooks/api` SDK.

## Install

```bash
npm install -g @haseebuchiha/freshbooks-cli
```

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).

```bash
freshbooks auth login \
  --client-id "<FRESHBOOKS_CLIENT_ID>" \
  --client-secret "<FRESHBOOKS_CLIENT_SECRET>" \
  --manual
```

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: `freshbooks auth status`

## Auth commands

- `freshbooks auth login --client-id <id> --client-secret <secret> --manual` -- authenticate via OAuth2 OOB flow
- `freshbooks auth logout` -- clear stored tokens and credentials
- `freshbooks auth status` -- show account ID, token expiry, and auth state
- `freshbooks auth refresh` -- manually refresh the access token

## Clients commands

- `freshbooks clients list [-p <page>] [--per-page <n>] [-s <search>]` -- list clients, search by org name
- `freshbooks clients get <id>` -- get a single client by ID
- `freshbooks clients create [--fname <name>] [--lname <name>] [--email <email>] [--organization <org>]` -- create a client
- `freshbooks clients create --data '<json>'` -- create with full JSON payload
- `freshbooks clients update <id> --data '<json>'` -- update a client

Example: `freshbooks clients create --fname "Taha" --organization "abcg.io"`

## Invoices commands

- `freshbooks invoices list [-p <page>] [--per-page <n>]` -- list invoices
- `freshbooks invoices get <id>` -- get a single invoice by ID
- `freshbooks invoices create --client-id <id> [--lines '<json>']` -- create an invoice with line items
- `freshbooks invoices create --client...