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, npm and direct downloads are on the download page.

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.

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

Run commands

firmary clients list
firmary tasks list --limit 20
firmary invoices get <invoice-id>

Everyday work has its own commands: clients, contacts, tasks, requests, messages, invoices, engagements and staff. firmary help lists them all.

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.

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. Without the command line, Codex and Claude Code can use npx @firmary/mcp connect.

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 firmary command line (install: curl -fsSL https://firmary.app/install.sh | sh,
or npx @firmary/cli). 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.
NO_COLOR: No colour.

Update or remove

To update, run the install command again, or your package manager’s own: brew upgrade firmary, winget upgrade Firmary.CLI, scoop update firmary or npm install -g @firmary/cli@latest.

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.