freeagent

A small CLI for the FreeAgent API, built in Go.

Features

• OAuth login (local callback or manual paste)
• Keychain-backed token storage with file fallback
• Create and send invoices
• Break-glass raw command for any FreeAgent endpoint
• JSON output mode for scripting / agents

Install

go build ./cmd/freeagent

Configure

Create a FreeAgent API application and note the client ID + secret.

Save app credentials:

./freeagent auth configure \
  --client-id YOUR_ID \
  --client-secret YOUR_SECRET \
  --redirect http://127.0.0.1:8797/callback

You can also use env vars:

export FREEAGENT_CLIENT_ID=...
export FREEAGENT_CLIENT_SECRET=...
export FREEAGENT_REDIRECT_URI=http://127.0.0.1:8797/callback

Login

Local callback (default):

./freeagent auth login

Manual flow:

./freeagent auth login --manual

Usage

Create a draft invoice:

./freeagent invoices create \
  --contact CONTACT_ID \
  --reference INV-001 \
  --lines ./invoice-lines.json

You can also pass a contact name or email and the CLI will resolve it:

./freeagent invoices create \
  --contact "Acme Ltd" \
  --reference INV-002 \
  --lines ./invoice-lines.json

Send an invoice email:

./freeagent invoices send --id INVOICE_ID --email-to you@company.com

Mark as sent (no email):

./freeagent invoices send --id INVOICE_ID

Break-glass request:

./freeagent raw --method GET --path /v2/invoices

Contacts:

./freeagent contacts list
./freeagent contacts search --query "Acme"
./freeagent contacts get --id CONTACT_ID
./freeagent contacts create --organisation "Acme Ltd" --email accounts@acme.test

Bank transactions (bulk approve):

./freeagent bank approve \
  --bank-account BANK_ACCOUNT_ID \
  --from 2025-01-01 \
  --to 2025-01-31

./freeagent bank approve --ids ./transaction-ids.txt
./freeagent bank approve --ids ./explanation-ids.txt --ids-type explanation

Files

• Config: ~/.config/freeagent/config.json
• Tokens (fallback): ~/.config/freeagent/tokens/PROFILE.json

Notes

• Default API base URL is production; use --sandbox for the sandbox API.
• Use --json to print raw JSON for automation or piping into other tools.

License

MIT. See LICENSE.