The arc CLI
@joinarc/cli is the official command-line client for the Arc API. The package is
@joinarc/cli; the command is arc. It's read-only today (see the API).
Install
npm install -g @joinarc/cli
arc --version
Requires Node.js 20+.
Authenticate
arc reads an API key (arc_sk_…) you create under Settings → Developer. Save it with
arc config add — every later arc call reads ~/.arc/config, so the key outlives the shell
you set it up in:
arc config add # prompts for the key — input is hidden, nothing hits your shell history
arc status # shows the resolved profile/URL and whether a key is set (no API call)
An API key on the command line is written to your shell history, so arc config add asks
for it instead. For automation, pipe it in (cat key.txt | arc config add) or pass
--token arc_sk_… — the dashboard's copy-runnable command uses --token so setup stays
one paste, which does put the key in history; rotate the key if that matters on a shared
machine.
arc config add verifies the key against the API before writing anything — it prints the
company and owner behind the key, so it doubles as the "does it work?" check — then saves
it to ~/.arc/config (owner-only permissions) twice: as default, which plain arc
commands use, and under an alias named for the key's company (override with --profile <name>).
The file is JSON, and holds a named profile per Arc account — pick one with
--profile <name>:
{
"default": { "token": "arc_sk_…" },
"acme": { "token": "arc_sk_…" }
}
Connecting a second Arc account is just another arc config add: the new key takes over
default and gets its own alias, while every earlier account keeps its profile — reach
one with --profile acme.
ARC_TOKEN and --token remain available for one-off calls and CI, and override the file.
Resolution precedence, highest first:
- Token:
--token→ARC_TOKEN→~/.arc/config - API URL:
--api-url→ARC_API_URL→~/.arc/config→ production default - Profile:
--profile→ARC_PROFILE→default
Permissions
An API key can only read what the Arc user who created it can read in the dashboard. Cash
management commands (accounts, transactions, payments, statements,
external-accounts, accounting-connections, invoices, invoice-recipients, and
treasury summary|positions) require that user's Treasury view permission. Downloading a
statement additionally requires permission to view account numbers, and payments requires
the payments permission. cards --scope team mirrors the dashboard's Team cards tab and
requires the same permission; cards --scope own remains available without it.
When permission is denied, the command exits 3. The key is still valid, so ask a company
admin for access rather than reissuing it. Permissions are checked on every request, so role
changes take effect immediately on existing keys.
Commands
Every list command paginates with --limit (1–100, default 25) and --cursor.
Transaction and invoice lists also accept --from/--to (inclusive, YYYY-MM-DD, on the
transaction date and the invoice issue date respectively). Values that can't work are
rejected locally, before any request: --limit abc, --limit 500, --from last-monday
and --timeout 0 all exit 2 naming the flag.
A command group runs its main read when you don't name a subcommand: arc accounts is
arc accounts list, arc org is arc org get. config and skills have no default —
they write, so they list their subcommands instead.
Every list table leads with an Id column, and transactions add the Account the row
belongs to (matching the Id in arc accounts list) — those are the ids get <id> and
download <id> take.
For a command's flags, examples, and response fields: arc help <command>.
Identity & organization
| Command | Returns |
|---|---|
arc whoami | The company, owner, and key behind the token. |
arc status | Resolved profile, API URL, and the key it would use — masked, with the source it came from, or the reason it can't be used (local; no API call). |
arc profile get | Your personal profile — legal name, email, phone, address; adds date of birth, job title, ownership %, and citizenship once your identity is verified. |
arc org get | The company's organization profile — legal name, DBA, masked EIN, phone, legal address. --investment-preferences adds investment preferences. |
arc users list | Company members: name, email, role, status. --email resolves one member exactly (any casing); --name matches a name substring; --role/--status narrow by kind. |
Accounts & transactions
| Command | Returns |
|---|---|
arc accounts list | Cash-management accounts and their balances. --type treasury|operating narrows by product; --status selects a state by the name the app gives it — ACTIVE, ACCOUNT_RESTRICTED, PENDING_APPROVAL, ACCOUNT_CLOSED. The list defaults to open accounts (ACTIVE and ACCOUNT_RESTRICTED); naming another state returns it. |
arc cards list | Arc-issued cards: masked last-4, form factor, cardholder, status, spend limit. --last4 selects one card exactly (cards carry no public id); --scope, --status, --form-factor, --cardholder narrow the list. |
arc external-accounts list | Linked external bank accounts: institution, masked number, type, status. Filter --type checking|savings, --status active|inactive. |
arc transactions list | Transactions, newest first, filtered server-side (below). |
arc transactions get <id> | Full detail for a single transaction, including isInternalTransfer. |
arc transactions list filters are applied server-side, so you fetch only the rows you asked for.
They combine freely, and each stays in effect while paging with --cursor:
| Flag | Filters on |
|---|---|
--account <id> | One account — the Id from arc accounts list, or a row's accountArn. |
--direction debit|credit | Money out, or money in. |
--status OPEN|POSTED|VOID|RETURNED | The status the rows report; POSTED is settled. |
--method <method> | ach and wire match every variant of each; or name one — ach-credit, ach-debit, ach-transfer, wire-credit, wire-debit, wire-transfer, international-wire-transfer, card, check-deposit, internal-transfer, rewards-redemption. |
--min-amount / --max-amount | Dollars (10000.50), matched against the amount's magnitude — the same bound covers debits and credits. |
--search <text> | Case-insensitive substring across the transaction — the counterparty or merchant name, the description and notes, and bank/account identifiers are all matched. Broader than a name filter. |
--from / --to | Date window, YYYY-MM-DD. |
--exclude-internal-transfers | Omits self-transfers and treasury sweeps. |
Payments
| Command | Returns |
|---|---|
arc payments list | Outgoing payments in one uniform shape. All states are returned by default; --status <all|paid|scheduled|draft|pending-approval|canceled> filters the list. |
arc payments get <id> | Detail for a single payment in any lifecycle state. |
arc payments list filters also run in the database, across every lifecycle state at once:
| Flag | Filters on |
|---|---|
--counterparty <text> | Case-insensitive substring on the payee name. |
--method <method> | wire covers domestic and international wires; or name one — ach, intra-transfer, international-wire, international-wire-fee. Drafts report no method, so any --method excludes them. |
--min-amount / --max-amount | Dollars (10000.50), matched against the amount the row shows. |
--from / --to | Date window, YYYY-MM-DD, on the single Date the row displays — sent for a paid payment, else scheduled, else created. |
Statements
| Command | Returns |
|---|---|
arc statements list | Available monthly account statements. --account <id> (the Id from arc accounts list), --month 2026-06, and --year 2026 narrow the list. |
arc statements download <id> | Downloads a statement PDF (--output <file>; defaults to arc-statement-<id>.pdf). |
Reach one month directly rather than paging for it:
arc statements list --account a1b2c3d4 --month 2026-06 --format json
Statement PDFs draw on a small per-company hourly budget shared with the Arc app — download the statements you need rather than looping the whole list, and cache the file.
Invoices
| Command | Returns |
|---|---|
arc invoices list | Invoices you've sent (money in): number, recipient, title, issue date, due date, total. Filter server-side: --recipient (name substring), --number (exact), --due-from/--due-to (due-date range), --overdue (due before today — invoices carry no payment status, so this is a due-date test only), --from/--to (issue-date range). |
arc invoices get <id> | One invoice's detail: the list row plus the sender's note and every line item. |
arc invoice-recipients list | The customers you bill: name, email, when added; adds each structured billing address in --format json. Alphabetical by name. |
Treasury
| Command | Returns |
|---|---|
arc treasury summary | Invested-account overview: total value (matches arc accounts list), cash available to trade, net yield (bps), interest/dividend earnings. |
arc treasury positions | Holdings, one uniform row each (cash / MMF / T-bill / …): market value, shares, net yield (bps), maturity. |
arc treasury rates | Current money-market fund rates (gross + net of your fees), highest-yield highlights, and the cash-sweep rate. |
Accounting
| Command | Returns |
|---|---|
arc accounting-connections list | Accounting integrations (QuickBooks/Xero links + bank feeds) and their sync status: provider, type, status, last synced. |
Reference & agent setup
| Command | Returns |
|---|---|
arc openapi | Prints the full /v1 OpenAPI spec (offline) — the machine-readable definition of every response shape. |
arc schema [resource] | Prints one resource's response schema offline (e.g. arc schema payments); omit the resource to list the available schemas. |
arc skills list / arc skills install | Manage the agent skills that teach an AI agent how to use this CLI (see Connect your AI agent). |
Output format
Every command supports a global --format:
--format table(default) — human-readable.--format json— pretty JSON (structured;Moneyis{ minorUnits, currency }).--format jsonl— newline-delimited JSON, one row per line — ideal for piping tojq -c/grep.
Response shapes
The exact fields each command returns are defined once, machine-readably. Discover them
offline: arc schema <resource> for a single resource, arc openapi for the whole
spec, or arc <command> --help (each carries a Response fields section). You can also browse
the rendered API reference. These pages describe what each command
does and when to reach for it — not its field-by-field layout.
Exit codes
Stable, so scripts and agents can branch on $?:
| Code | Meaning |
|---|---|
0 | success |
2 | usage error (bad flags / missing or malformed key) |
3 | auth failed — bad/expired key (401) or your Arc user lacks permission for that data (403) |
4 | rate limited (429) |
5 | API error (5xx, unexpected status, or a 2xx body that isn't JSON) |
6 | network error (timeout, DNS, connection) |
70 | unexpected CLI bug |
Every API failure names the server's own error code (e.g. invalid_cursor) so a caller can
branch on why it failed. Only an opaque failure — a 5xx, or a status the CLI doesn't
model — adds a Request id: line, the handle support uses to find that exact request. The
self-explanatory ones don't, since there is nothing to escalate: 2/3/4, and the two
other 5s (a 404, or a 2xx body that isn't JSON).