Firmary

Command line guide

Docs · firmary.app

firmary runs the same operations as the Firmary app, API and MCP, under the same permissions and approvals. It is for firm staff, their scripts and their AI agents.

Install

macOS and Linux
curl -fsSL https://firmary.app/install.sh | sh
Windows (PowerShell)
powershell -c "irm https://firmary.app/install.ps1 | iex"

Homebrew, Scoop and direct downloads are on the download page.

Sign in

firmary auth login

Your browser opens Firmary’s sign-in page; sign in as usual. Over SSH, or with --device, it shows a code to enter on another device instead. The sign-in is kept in your system’s keychain.

On a Linux computer or server with no keychain, sign in with firmary auth login --store file. The sign-in is then kept in a file only you can read.

firmary auth status shows who is signed in, and firmary auth logout signs out and removes the sign-in from this computer.

The full-screen app

firmary

firmary on its own, or firmary ui, opens the full-screen app in your terminal. Home shows what needs you: approvals, overdue and blocked work, unread messages and what is coming up. The numbers 1 to 7 go to Home, Work, Clients, Requests, Messages, Billing and More; a goes to Agents and approvals.

/ finds a client by name, ⌃K finds any action, and ? lists the keys that work where you are. The line at the bottom shows the ones for the screen you are on. In a message thread, r replies; every change and every message shows you what it will do, and the equivalent command, before it runs.

To open straight on a screen, add its name, as in firmary ui messages. The screens are home, work, clients, requests, messages, billing, more, agents and activity.

If you work at more than one firm, press ⌃K and choose Switch firm. The first time, you sign in to that firm; after that, switching is immediate. Each firm’s sign-in is saved as a profile named after the firm, such as firm-harbor-cpa, and commands reach that firm with --profile firm-harbor-cpa.

Run commands

firmary clients list
firmary tasks list --limit 20
firmary invoices get INV-0008

Everyday work has its own commands: clients, contacts, tasks, requests, messages, invoices, engagements and staff. firmary help lists them all. Name a record the way you know it: a client’s name, an invoice number such as INV-0008, or its ID.

To have Tab complete commands, fields and client names, run this once:

firmary completions install

Everything else Firmary can do is an operation. Find one by what you want to do, see its fields, then run it:

firmary op search "invite a contact"
firmary op describe <operation-id>
firmary op run <operation-id> --<field> <value>

Every command takes --json. Lists come a page at a time with --limit and --cursor, and --all streams every page. --fields id,name keeps only the fields you name. Long tables open in a pager; --no-pager prints straight to the terminal, and FIRMARY_PAGER=cat or PAGER=cat turns paging off for good.

Approve what agents ask

When an AI agent asks to make a change your firm wants a person to approve, the change waits for you. Approve it in Firmary, or here:

firmary approvals list
firmary approvals get <approval-id>
firmary approvals approve <approval-id>

get shows exactly what the agent will run. Firmary may ask you to confirm it’s you in the browser before an approval counts. firmary approvals decline turns a request down; nothing runs.

AI agents

Give an agent its own access: you sign it in once, and from then on it acts under your firm’s AI policy and approvals, and what it does shows in firmary activity list.

firmary auth login --agent

Agents get JSON and are never asked questions. firmary help --json is the whole contract: every command, flag, exit code and output shape. A change that needs approval ends with exit code 7 and a link for a person; the agent then runs firmary approvals wait <approval-id>, which finishes exactly what was approved. An agent can’t approve its own requests, and --yes never counts as an approval.

To add Firmary to an AI app as an MCP server:

firmary mcp install --client claude-code

The client can also be codex, cursor or vscode; --print shows the change without making it.

To have a coding agent reach for Firmary by itself, add this to the project’s AGENTS.md or CLAUDE.md:

AGENTS.md
## Firmary
This firm's clients, work, documents, messages and billing are in Firmary.
Use the installed firmary command line, not a package runner. Install it with
curl -fsSL https://firmary.app/install.sh | sh, Homebrew or Scoop
(firmary.app/download). Run firmary help --json for every command; add --json
to any command. Exit code 7 means a person must approve: give them the link, then run
firmary approvals wait <approval-id>.

Exit codes

0
Done (an empty list too).
1
Something went wrong, even after retrying.
2
A flag or an input is wrong or missing. The message names every missing field.
3
Not found, or more than one record matches (the matches are listed).
4
Sign in first, or again: firmary auth login.
5
You, or the agent, aren't allowed to do this.
6
The record changed since it was read. Read it again, then retry.
7
Waiting for a person to approve. The output has the approval ID and a link.
8
Too many requests. The output says when to try again.
9
Firmary can't be reached.
130
Cancelled with Ctrl-C.

Settings for scripts

FIRMARY_TOKEN
A service token for CI. Read from the environment, never saved.
FIRMARY_PROFILE
Which saved sign-in to use.
FIRMARY_OUTPUT
table, json, ndjson, csv or id.
FIRMARY_NO_INPUT
1: never ask a question; missing input ends with exit 2.
FIRMARY_AGENT
Your agent's name, recorded as a label. Never a permission.
FIRMARY_STORE
file: keep the sign-in in a file only you can read, instead of the system keychain.
FIRMARY_PAGER
The program long tables open in. cat turns paging off. PAGER works too.
NO_COLOR
No colour.

Update or remove

To update, run the install command again, or your package manager’s own: brew upgrade firmary, scoop update firmary. firmary --version shows the version you have; the latest is 0.2.4.

To remove it, sign out first with firmary auth logout, then delete the program: ~/.local/bin/firmary on macOS and Linux, or %LOCALAPPDATA%\Programs\Firmary\firmary.exe on Windows, if you used the install scripts. Package managers remove it with their own uninstall command.

Questions or problems: support@firmary.app.