# Arc — Developer Platform (API & CLI)

> Read-only /v1 REST API and the arc CLI give an AI agent (or a developer) secure, company-scoped access to a startup's financial data — cash management, treasury, payments, invoices, cards, accounting connections. Authenticate with an API key (arc_sk_…); the CLI ships agent skills (arc skills install) that teach an agent when and how to use it.

This file contains all documentation content in a single document following the llmstxt.org standard.

## Arc Developer Docs


The Arc developer platform provides **read-only** access to your company's financial data
through a REST API (`/v1`) and the `arc` command-line tool. Requests authenticate with an
API key created under [**Settings → Developer**](https://app.joinarc.com/settings/developer).

:::tip Start here
[**Connect your AI agent →**](./getting-started/connect-your-agent.md) — from a fresh API key
to an agent answering questions about your finances in a few commands.
:::

## Reference

- **[API](./api/overview.md)** — the `/v1` REST surface: auth, resources, and conventions.
- **[CLI](./cli/overview.md)** — the `arc` command-line tool built on that API: install,
  authenticate, and the available commands.
- **[MCP](./mcp/overview.md)** — a one-click connector for no-shell assistants (coming soon).

---

## Connect your AI agent


Connect an AI agent such as Claude Code, Codex, Cursor, or Claude Cowork to your Arc
financial data. With the **`arc` command-line tool** and an API key, your agent can answer
questions like *"What did we spend on vendors last month?"* or *"What's our cash position
across accounts?"*

## Prerequisites

- Create an [Arc account](https://app.joinarc.com/signup) and add an MFA method to your login.
  MFA is required to create an API key.
- Install **Node.js 20 or newer** on the machine where your agent runs.

## Step 1: Create an API key

1. In the Arc dashboard, go to [**Settings → Developer**](https://app.joinarc.com/settings/developer).

   ![The Developer tab under Settings, before any keys exist](/img/developer-settings.png)

2. Click **Create key**, name it `arc-cli`, and choose whether to set an expiration date.
   If you leave the date blank, the key will not expire on its own. Complete the MFA prompt.

   

3. **Copy the key now.** It starts with `arc_sk_` and is only shown once. If you lose it,
   rotate the key to get a new one.

   

You can review a key and its activity any time under [**Settings → Developer**](https://app.joinarc.com/settings/developer).

Use of the Arc CLI and API is subject to the [**Arc Developer Terms**](https://vault.pactsafe.io/s/302d718c-fd8b-4f36-8743-b75c207b8fac/legal.html#template-e05zpsvbh).

## Step 2: Connect your agent

The CLI works with **any agent that can run a shell**, including Claude Code, Codex, Cursor,
and Gemini CLI. Install the CLI, add your key with `arc config add`, and start the agent.
The CLI remembers the profile for future sessions, so you do not need to keep an environment
variable active.

The bundled skills install to both `~/.claude/skills` and the vendor-neutral
`~/.agents/skills` by default. To install them in one specific folder instead, run
`arc skills install --dir <path>`.

### Terminal agents (Claude Code, Codex, Cursor, …)

In your terminal:

```bash
# 1. Install the CLI (Node 20+) and Arc's agent skills
npm install -g @joinarc/cli && arc skills install

# 2. Add the key you created under Settings → Developer
arc config add     # paste the key at the prompt; it stays hidden
```

`arc config add` verifies the key, shows the company and owner, and creates a default profile
and a [named profile](../cli/overview.md#authenticate) for the company. It keeps any profiles
you already have. To connect another Arc account later, run `arc config add` again.

The dashboard also provides a one-line command with your key already filled in:
`arc config add --token …`. This is quicker, but it puts the key in your shell history.
Use the interactive prompt above if you want to keep the key out of your history.

Start your agent from any terminal and ask it a question. The CLI uses the profile you added,
so you do not need to paste the key into the chat.

Prefer an environment variable for a throwaway shell or CI? `ARC_TOKEN` still works and takes
precedence over a saved profile. See [Authenticate](../cli/overview.md#authenticate) for details.

### Claude Cowork

Cowork runs commands in its own sandbox, so set it up in plain English:

> Install the Arc CLI with `npm install -g @joinarc/cli`, run `arc skills install`, and save my
> Arc API key with `arc config add`. The full docs are at
> [https://docs.joinarc.com/llms-full.txt](https://docs.joinarc.com/llms-full.txt). Then use it to answer questions about my finances.
> My key is: `arc_sk_…`

It installs the tool and skills and takes it from there. Unlike the terminal setup, this puts
your key in the chat. Treat that conversation as sensitive, and revoke the key if it is exposed.
Cowork runs in a sandbox, so if it can't reach Arc, allow `api.arc.tech` in its network settings.

**Make it persist across sessions.** Each Cowork chat starts a fresh sandbox, so a one-off
`npm install` is gone by the next session. Cowork's cloud **environment** caches the filesystem
its **setup script** produces, so add the install there once:

```bash
npm install -g @joinarc/cli && arc skills install || true
```

Then `arc` and the skills are ready in every later session (the cache refreshes about weekly and
whenever you edit the setup script). Two caveats: there's no persistent home directory or secrets
store yet, so your `arc_sk_` key is still supplied per session (with `arc config add` or the prompt
above); and a repo-committed `.claude/` config carries over, but a user-level `~/.claude` does not.

### No-shell assistants (ChatGPT, Claude.ai, Slack)

These can't run a command-line tool. A one-click MCP connector is coming. See
[**MCP**](../mcp/overview.md). For now, use a terminal agent or Cowork.

## Step 3: Ask your agent

Once connected, ask a question. The agent will use the `arc` tool to fetch what it needs.
For example:

- "What were my largest transactions in the last 30 days?"
- "What's my total cash position across all accounts?"
- "Summarize spending by counterparty last quarter."
- "Pull up the details of my most recent ACH transfer."

<video controls muted playsInline poster="/img/arc-agent-demo-poster.png" width="100%" style={{ maxWidth: '760px', borderRadius: '8px', display: 'block' }}>
  <source src="/video/arc-agent-demo.mp4" type="video/mp4" />
</video>

## What your agent can (and can't) do

**Your agent can:**

- Read transactions, accounts, and balances.
- Read cards, payments, statements, and invoices.
- Read treasury holdings and accounting-connection status.
- Use any read-only command listed in the [CLI reference](../cli/overview.md).

**Your agent can't:**

- Move money or create transfers.
- Change settings or other data.
- See any company other than the one the key belongs to.

## Key lifecycle

A key belongs to the person who created it, so its access tracks yours automatically:

- **It acts with your permissions.** If your access changes, the key's access changes with it.
- **It stops working if you're deactivated or leave the company.** Every request re-checks the
  key against your account, so an offboarded owner's keys can't be used.
- **Expiration is optional.** Set one when you create the key, or leave it blank and the key
  doesn't expire on its own. Retire it by revoking or rotating it.

## Manage or revoke access

Everything is managed from [**Settings → Developer**](https://app.joinarc.com/settings/developer):

- **Revoke** stops a key immediately. Use it when a key is no longer needed or may be exposed.
- **Rotate** replaces a key with a new one and shows the new secret once. You can rotate keys
  on a regular schedule or whenever you suspect one has been exposed.
- **Activity** shows who created, rotated, revoked, or renamed a key, and when it happened.

## Troubleshooting

- **`arc whoami` fails:** a **missing** key is a usage error (exit code 2). The CLI found no
  key in `--token`, `ARC_TOKEN`, or a saved profile. A **wrong, expired, or revoked** key is an auth
  error (exit code 3). Either way, run `arc status` to see which key the CLI resolved and where it
  came from, or create a fresh key and add it with `arc config add`.
- **`arc: command not found`:** the CLI isn't installed or isn't on your `PATH`. Re-run
  `npm install -g @joinarc/cli` and confirm with `arc --version`.
- **"Create key" is blocked:** set up an MFA method on your Arc login first. It's required
  to create a key.

## Security

Arc API keys are designed to give agents narrow, controlled access:

- **Read-only:** An agent can read your financial data, but it cannot move money or make changes.
- **Company-scoped:** A key can only access the company it was created for.
- **Permission-scoped:** A key has your permissions and never has more access than you do.
- **Protected by MFA:** You must complete an MFA prompt to create a key.
- **Auditable:** You can review key activity under **Settings → Developer**.
- **Revocable and rotatable:** You can revoke access immediately or replace a key at any time.

You are giving a key to a tool that runs on your machine or in your agent's sandbox, not
connecting Arc directly to a third party. You remain in control of the key and can revoke it
whenever you need to.

---

## API

# The Arc API (`/v1`)

The `/v1` REST API is what the [`arc` CLI](../cli/overview.md) is built on. It's
**read-only** today.

## Base URL

```
https://api.arc.tech/v1
```

## Authentication

Every request carries an API key (`arc_sk_…`) as a bearer token:

```
Authorization: Bearer arc_sk_your_key_here
```

Create and manage keys under [**Settings → Developer**](https://app.joinarc.com/settings/developer). A key is company-scoped, acts
with its owner's permissions, and every failed auth returns a generic `401` (no
enumeration oracle).

## Resources

List endpoints are paginated (`limit`/`cursor`, per the list envelope below). Transaction
and invoice lists also accept `from`/`to` (inclusive, `YYYY-MM-DD`, on the transaction date
and the invoice issue date respectively).

### Identity & organization

| Method & path | Description |
|---|---|
| `GET /v1/me` | The identity behind the key (company, owner, key metadata). |
| `GET /v1/profile` | The key owner's personal profile (name, email, phone, address, and KYC details when verified). |
| `GET /v1/organization` | The company's organization profile (legal name, DBA, masked EIN, phone, legal address). `?investmentPreferences=true` also returns investment preferences. |
| `GET /v1/users` | Company members — name, email, role, status. Filter with `?role`, `?status`, `?email` (exact, any casing), `?name` (substring). |

### Accounts & transactions

| Method & path | Description |
|---|---|
| `GET /v1/accounts` | Cash-management accounts and balances. Filter with `?type=treasury\|operating` and `?status=ACTIVE\|ACCOUNT_RESTRICTED\|PENDING_APPROVAL\|ACCOUNT_CLOSED` — the app's own name for each state. Defaults to open accounts; naming another state returns it, with zero balances where there is no ledger. |
| `GET /v1/cards` | Arc-issued cards — masked last-4, form factor, cardholder, status, spend limit. Filter with `?scope`, `?status`, `?format`, `?cardholder`, `?last4` (exact — the only per-card handle). |
| `GET /v1/external-accounts` | Linked external bank accounts (the app's "Linked Accounts") — institution, masked number, type, status. Filter with `?type=checking\|savings` and `?status=active\|inactive`. |
| `GET /v1/transactions` | Cash-management transactions. Filter with `?account`, `?direction`, `?status`, `?method`, `?minAmount`/`?maxAmount` (integer minor units, matched on the amount's magnitude), `?search`, `?from`/`?to`, `?excludeInternalTransfers=true`; see the [API reference](/api-reference) for each parameter's values. |
| `GET /v1/transactions/:id` | A single transaction's detail, including `isInternalTransfer`. |

### Payments

| Method & path | Description |
|---|---|
| `GET /v1/payments` | Outgoing payments in one uniform shape. All lifecycle states are returned by default; `?status=` can select one state. Filter with `?counterparty`, `?method`, `?minAmount`/`?maxAmount` (integer minor units), and `?from`/`?to` (the single date the row displays); see the [API reference](/api-reference) for each parameter's values. |
| `GET /v1/payments/:id` | A single payment's detail, in any lifecycle state. |

### Statements

| Method & path | Description |
|---|---|
| `GET /v1/statements` | Available monthly account statements. Filter with `?account` (an id from `/v1/accounts`), `?month=2026-06`, and `?year=2026`. |
| `GET /v1/statements/:id/download` | A short-lived signed URL to download a statement PDF. |

### Invoices

| Method & path | Description |
|---|---|
| `GET /v1/invoices` | Invoices you've sent — money in. Filter with `?recipient` (name substring), `?number` (exact), `?dueFrom`/`?dueTo` (due-date range), `?overdue=true` (due before today — a due-date test only; invoices carry no payment status), `?from`/`?to` (issue-date range). |
| `GET /v1/invoices/:id` | A single invoice's detail — the list row plus the sender's note and its line items. |
| `GET /v1/invoice-recipients` | The customers you bill — who your invoices are sent to, with each billing address. |

### Treasury

| Method & path | Description |
|---|---|
| `GET /v1/treasury/summary` | Treasury (invested) account overview: total value (matches `/v1/accounts`), cash to trade, net yield (bps), earnings. |
| `GET /v1/treasury/positions` | Treasury holdings in one uniform row shape (cash / MMF / T-bill / …), with per-position net yield (bps). Holdings are a small bounded set, so all of them come back in one page — this route takes no `limit`/`cursor`. |
| `GET /v1/treasury/rates` | Current money-market fund rates (gross + net of your fees), highest-yield highlights, cash-sweep rate. |

### Accounting

| Method & path | Description |
|---|---|
| `GET /v1/accounting-connections` | Accounting integrations (QuickBooks/Xero links + bank feeds) with normalized sync status. |

## Conventions

- **List envelope:** list endpoints return `{ "data": [ … ], "nextCursor": string | null }`.
  Page by passing `nextCursor` back as the `cursor` parameter until it's `null`.
- **Money:** always `{ "minorUnits": <integer>, "currency": "USD" }` — integer minor
  units (cents), never a float, so clients can do exact math.
- **Dates:** ISO-8601 strings in UTC.
- **Tenant scoping:** every response is scoped to the key's company; an id from another
  company is reported as not found.
- **Query parameters:** each endpoint rejects any parameter it doesn't support — a typo'd
  filter, or one that belongs to another endpoint, is a `400 invalid_parameter` rather than
  being silently dropped, so a filtered read is either applied or refused. A few endpoints
  accept filters the spec doesn't list yet, so treat the documented set as the supported
  minimum rather than the exact accepted set.
- **Response shapes:** the exact schema of every resource is the OpenAPI spec — run
  `arc openapi` (or fetch [`/v1/openapi.json`](https://api.arc.tech/v1/openapi.json)) rather
  than relying on shapes copied into prose. This page says what each resource *is*, not its
  field-by-field layout. Or browse the [**API reference**](/api-reference).

## Rate limits

Requests are rate-limited per key **and** per company — creating or rotating keys does
not raise a company's ceiling. Every response carries `X-RateLimit-Limit`,
`X-RateLimit-Remaining`, and `X-RateLimit-Reset` for whichever of the two you are
closest to; a `429` carries `Retry-After` (seconds) and means you should back off.

Statement PDFs are generated on demand, so `GET /v1/statements/:id/download` draws on a
separate, much smaller **per-company hourly budget** shared with the Arc app. Download
the statements you need rather than sweeping the whole list, and cache the PDF — the
signed URL expires in minutes, but re-requesting the same statement spends the budget
again.

---

## CLI

# 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](../api/overview.md)).

## Install

```bash
npm install -g @joinarc/cli
arc --version
```

Requires Node.js 20+.

## Authenticate

`arc` reads an API key (`arc_sk_…`) you create under [**Settings → Developer**](https://app.joinarc.com/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:

```bash
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>`:

```json
{
  "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:

```bash
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](../getting-started/connect-your-agent.md)). |

## Output format

Every command supports a global `--format`:

- `--format table` (default) — human-readable.
- `--format json` — pretty JSON (structured; `Money` is `{ minorUnits, currency }`).
- `--format jsonl` — newline-delimited JSON, one row per line — ideal for piping to
  `jq -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](/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 `5`s (a `404`, or a 2xx body that isn't JSON).

---

## Agent skills


The `arc` CLI ships **agent skills** — small, open-format ([agentskills.io](https://agentskills.io))
`SKILL.md` files that teach an AI agent *when* to reach for the CLI and *how* to compose it, not
just what each command does. Install them into your agent's skills directory:

```bash
arc skills install     # copies the skills into ~/.claude/skills and ~/.agents/skills (or --dir <path>)
arc skills list        # show what's bundled
```

Once installed, an agent (e.g. Claude Code) can answer a real question — "what's our cash
position?", "what did we spend last month?" — by composing `arc` commands on its own.

## What's bundled

- **`arc-shared`** — the foundation every skill defers to: auth, `--format jsonl`, walking
  pagination to completion, the money/date/direction conventions, and read-only safety.
- **`arc-analyze-spend`** — where money went: categorized and counterparty breakdown, month-over-month.
- **`arc-cash-position`** — how much cash you have: operating balances plus the treasury (invested) account.
- **`arc-receivables`** — what customers owe: joins sent invoices to incoming transactions to infer paid vs. outstanding.
- **`arc-books-health`** — whether accounting data is flowing: connection sync status, as a trust gate before quoting book figures.

Skills are **task playbooks**, not one per command — the reference for individual commands is
[the CLI page](./overview.md) and `arc openapi`.

`arc skills install` is additive and idempotent — it only writes Arc's own `arc-*` skills, never
touching others.

---

## MCP

# MCP (coming soon)

The [`arc` CLI](../cli/overview.md) serves shell-capable agents like Claude Code and Cowork.
For assistants that can't run a command-line tool — ChatGPT, Claude.ai, Slack — Arc will
offer a **Model Context Protocol (MCP)** connector: one-click OAuth, no terminal, the same
read-only surface as the CLI.

For now, [connect an agent](../getting-started/connect-your-agent.md) through the CLI.