Developer Tools
CLI
The freeinvoiceautomation command line tool runs every API capability from your terminal and scripts, with the same permissions and modes as your API key.
Coming the week of 25 January 2027
This feature ships in the week of 25 January 2027. This page describes how it will work; details can change before release.
The freeinvoiceautomation CLI brings the whole API to your terminal. List overdue invoices, create a client, record a bank payment or export your items to CSV, all from a shell or a script. It is a thin client of the same API that the web app uses: it has no business logic of its own, so it can do exactly what your API key allows and nothing more.
Install
The CLI is published on npm as freeinvoiceautomation.
npm install -g freeinvoiceautomationThe stdio MCP client, freeinvoiceautomation-mcp, ships on npm at the same time. It lets MCP clients that only speak stdio reach our hosted MCP server with your API key. See Other MCP clients.
Sign in with an API key
The CLI authenticates with an API key, never with your password.
Create a key
In the web app, open Settings > API keys and create a key for the CLI. Choose the scopes you need. Keep the mode on draft only unless your scripts must send documents without a person confirming.
Give the key to the CLI
Set the key in your shell (or your CI secrets) so the CLI can read it. The exact sign-in options are set in the CLI spec before release.
export FIA_API_KEY=fia_your_keyCheck it works
List the businesses the key can reach:
freeinvoiceautomation business listThe key is bound to one account, so the CLI works in that account. To work in another account, create a key there.
How commands are named
Commands follow the pattern freeinvoiceautomation <noun> <verb> (proposed; confirmed in the CLI specification). Each command is generated from one API capability, so it has the same inputs, the same permission key and the same errors as the endpoint. The endpoint pages in the API reference show the CLI command for each capability.
Commands available at release
| Area | Commands |
|---|---|
| Businesses | business list, business get, business create, business update, business delete, business methods |
| Tax rates and numbering | tax-rate list, tax-rate upsert, tax-rate archive, numbering list, numbering update |
| Clients | client list, client get, client upsert, client delete, client contacts, client contact-upsert, client contact-delete, client credit |
| Items | item list, item get, item upsert, item archive, item import, item export |
| Documents | doc list, doc get, doc delete, doc versions, doc activity, doc overdue, doc send, doc send --preview, doc pdf, doc share, doc unshare, doc void, doc apply-credit |
| Invoices, estimates, receipts, credit notes | invoice create, invoice update, estimate create, estimate convert, receipt create, credit-note create |
| Payments | payment record, payment status, payment list, payment get, payment delete, payment refund, proof list, proof accept, proof reject |
| Connections | rail list, connection list, connection create, connection stripe, connection update, connection verify, connection delete |
| Messages and templates | message list, template messages, template message-upsert, template pdfs, template pdf-upsert, usage |
| Settings and account | settings get, settings set, account get, account update, account export, account delete, account transfer, file upload |
| Team | member list, member invite, member uninvite, member update, member deactivate, member reactivate, member remove, role list, role create, role update, role delete, role reset, audit list |
| Developers | key list, key create, key revoke, webhook list, webhook upsert, webhook delete, webhook test, webhook deliveries, webhook redeliver, connector list, connector unlink |
| Billing | billing get, billing card-add, billing card-remove, credits buy, credits packs |
| Reminders, late fees, recurring | reminder list, reminder upsert, reminder delete, doc remind, doc promise, late-fee list, late-fee upsert, late-fee delete, late-fee waive, recurring list, recurring upsert, recurring pause, recurring resume, recurring delete |
| Schedules and reports | doc schedule, doc schedule --show, doc schedule --remove, report aged, report get, report export |
| AI agent | agent run, agent runs, agent run-get, agent automations, agent automation-upsert, agent automation-delete |
credits buy does not charge anything: it prints the Stripe Checkout link for a credit pack, and you pay in the browser. Commands for features that ship later, such as contracts (contract create), time tracking (time log), expenses (expense record), accounting sync (accounting status) and the ledger (ledger report), are added in the CLI release that matches each feature.
A few actions need a fresh sign-in in the web app and cannot be done with an API key (proposed): connecting a payment rail, deleting a business, billing changes, creating an auto_send key, adding a billing card, buying a credit pack and deleting the account. The matching commands return fresh_signin_required; finish those actions in the app.
Examples
Each command's inputs are the capability's fields, as documented on its endpoint page. The exact flag syntax is set in the CLI specification; the examples show the intent.
# Invoices that are overdue
freeinvoiceautomation doc overdue
# All saved items of your business as CSV
freeinvoiceautomation item export > items.csvfreeinvoiceautomation doc send --preview <document-id>
freeinvoiceautomation doc send <document-id>Safety rules are the same
The CLI does not relax any rule of the API:
- Drafts first.
invoice createandestimate createcreate drafts. - Sends need confirmation from a
draft_onlykey. Without it you get the preview andconfirmation_required. With anauto_sendkey, sends run directly. - Destructive commands (
doc void,credit-note create,payment refund,key revokeand the others marked destructive in the API reference) always need confirmation, whatever the key's mode. - Idempotency. Writes carry an
Idempotency-Key, so a retried command does not create anything twice. See Idempotency. - Audit. Every write is recorded in the audit log with your API key as the actor.
See Drafts and confirmations for the details.
Using the CLI in scripts and CI
- Create a separate key for each script or pipeline, with only the scopes it needs.
- Store the key in your CI secret store, never in the repository. Keys start with
fia_(proposed), which secret scanners can recognise. - Respect rate limits: the CLI uses the same per-key budget as any other API client.
- Keys follow their creator's permissions. If the person who created the key loses a permission or leaves the account, the script loses it too.
Errors
The CLI shows the API's error code, message and request_id. Look the code up on Errors. Quote the request_id if you contact support.