
arc
moi.arc/arc
Your arc budget in any agent: 121 tools for accounts, transactions, debts and reports
Documentation
arc cli
arc cli connects to your budget through arc. It works with arc-managed servers, and with your own Actual server: an arc licence for it is free with any arc account. Once signed in, open Settings → AI agents to find the one-command CLI installer that is pre-baked with your instance URL and credentials.
arc is the installed CLI, TUI, and MCP surface for Actual Budget. One install gives you:
- an
arccommand-line interface covering accounts, transactions, categories and category groups, payees, tags, rules, schedules, budget months, savings goals, debts (cards, loans and BNPL plans: each cycle's amount due and state, statement figures, payoff maths and "Pay here first"), the statements the arc app files (figures, reconciled or not, the undo journal, payment due, fees worth asking back), budget templates, group splits, refunds, statement reconciliation, duplicate detection, investment portfolios, and reports - a terminal UI via
arc ui - a stdio MCP server via
arc mcpthat exposes every data operation as a structured tool for agents
Install
curl -fsSL https://raw.githubusercontent.com/ashrithps/arc-cli/main/install.sh | bash
There are two ways to connect arc to your budget. Both are supported, and they work side by side on the same budget.
Install with the command from the arc app
In the arc app, open Settings → AI agents and copy the install command it shows:
curl -fsSL https://raw.githubusercontent.com/ashrithps/arc-cli/main/install.sh | bash -s -- --payload '<json-payload>'
This works with every version of the arc app. The payload contains your API URL, API key, sync id, and (optionally) an encryption password. Treat it like a secret and run it only on a trusted machine. It gives arc full access to the budget it was generated for: every command and MCP tool runs straight away, and arc activity keeps a log of what agents did on this machine.
Your own Actual server (free arc licence)
If your budget lives on your own Actual server, the install command from the app also carries an arc licence signed for that server's address. The licence is free with any arc account. The CLI checks it on every run: it works for that one host, and a command without one is refused with a message saying how to get it. Self-hosted servers must use https, except on this machine or your private network (localhost, 10.x, 172.16–31.x, 192.168.x, *.local).
- Expiry. It lasts 30 days on the free plan (Premium: until your plan renews, plus a week) and renews itself. A paired machine does that in its last week; an unpaired install needs a fresh install command from the app.
arc auth statusshows the host and expiry. - Reverse-proxy headers. If your server sits behind Cloudflare Access or another proxy that needs headers, add them on the server connection screen in the app before copying the command. arc sends them only to your Actual server, never to anything else. On a paired machine they live in the Keychain with your other secrets.
ACTUAL_CUSTOM_HEADERS='[{"name":"…","value":"…"}]'overrides them for one run, andARC_CLI_LICENSEoverrides the stored licence.
Pair with approvals (Agent Controls)
Pairing needs an arc app that shows Connect a machine under Settings → AI agents. It arrives with the next app release; until your app has it, use the command above. You can pair an existing install later without reinstalling.
In the app, open Settings → AI agents → Connect a machine, choose how much agents may do, and copy the command it shows:
curl -fsSL https://raw.githubusercontent.com/ashrithps/arc-cli/main/install.sh | bash -s -- --pair <token> --agent claude-code
Already installed? Run arc auth pair <token> [--agent <key>] [--label <name>] with the token from the app.
The installer prints four words. Check that they match the ones on your phone, then approve with Face ID. Your budget's credentials arrive sealed to this machine's key and go straight into the macOS Keychain (or the Linux Secret Service), never into a file. If this machine was installed with a payload, pairing moves its existing secrets out of config.json into the Keychain. From then on:
- Agents ask before they change anything. Under the default Standard preset, reads run and every change waits for your approval on your phone. You can set each agent to Full, Standard or Private, override any group or operation with Allow, Ask or Deny, and approve once, for 15 or 60 minutes, or always.
- Approve from wherever you are. A push with Approve and Deny, a review sheet in the app, or the terminal.
- Touch ID on this Mac.
arc approvals enroll-maclets you approve writes here with Touch ID. Destructive changes always go to your phone. - A tamper-evident timeline.
arc activityshows what every agent did, day by day, and checks the server's hash chain so a rewritten history shows up as one. The same timeline is in the app. - Each agent is named. Calls are tagged with the agent that made them (Claude Code, Codex, Cursor, Gemini CLI and so on, detected automatically, or set with
--agent/ARC_AGENT), so you can give each one its own permissions or block it.
Agent Controls commands
| Command | What it does |
|---|---|
arc auth pair <token> | Pair this machine. --agent <key> names the agent, --label names the machine. |
arc auth status | Show whether this machine is paired, and with which fingerprint. |
arc agents whoami [--agent <key>] | What the current agent may do: runs, asks, or refused, per group and risk, plus any active time-limited approvals. |
arc agents list | The agents that have used arc on this machine, with how often they were asked or refused. |
arc approvals list | Requests waiting on you. |
arc approvals show <id> | One request in full. |
arc approvals approve <id> [--scope once|15m|60m|always] | Approve with Touch ID on this Mac (writes only; needs enroll-mac). |
arc approvals deny <id> | Refuse a request. |
arc approvals wait <id> | Wait for a decision, then run the approved call exactly once. |
arc approvals enroll-mac | Set up Touch ID approval on this Mac. You confirm it on your phone. |
arc activity [--agent <key>] [--since 2h|3d|2026-10-01] [--limit N] [--follow] [--json] | The timeline of what agents did, with the chain check. |
How a waiting call behaves
- In a terminal, a command that needs approval shows a spinner and waits for your phone; press
tto approve with Touch ID on an enrolled Mac, or Ctrl-C to cancel. - Without a terminal (an agent running the CLI), it waits up to 90 seconds (
ARC_APPROVAL_WAIT_SECONDSchanges this), then exits 75 with JSON naming the request.arc approvals wait <id>finishes it. A denial exits 77, and nothing was changed. - Over MCP, a tool waits up to 45 seconds, then returns
{"status": "pending_approval", "request_id": "…"}. The agent callsarc_agent_request_statusto finish it; the approved call runs exactly once.arc_agent_permissionslets an agent check up front what will need you. No tool can approve or deny anything. - Offline, a paired machine uses its last known permissions: allowed reads keep working for a day and allowed writes for 15 minutes, while anything that asks, anything destructive, and anything with no cached permissions is refused.
Once paired, enforcement cannot be switched off from this machine, and nothing on it can change your permissions: those live on your phone.
Use arc in Claude Code or as an MCP server
Install arc first, with either command above: the one from the arc app works with every app version, and pairing adds approvals on your phone. Both give agents the same skill, recipes and tools.
Claude Code plugin. The arc skill, each dashboard recipe as its own skill, and arc's MCP server:
claude plugin marketplace add ashrithps/arc-cli
claude plugin install arc@arc-moi
The installer already puts the arc skill in ~/.claude/skills/arc; the plugin adds the recipes as skills and the MCP tools, and updates with this repo.
Any MCP client. arc mcp is a stdio MCP server with one tool per command in the catalog below, and every dashboard recipe as a prompt (recipe-spending, recipe-budget and the rest; Claude Code lists them as slash commands). The installer adds it to Claude Desktop. Elsewhere, add a server that runs arc with the argument mcp, for example in Claude Code without the plugin:
claude mcp add arc -- arc mcp
For Claude.ai on the web or phone, see Remote MCP below. On a paired machine every tool call goes through your approvals, whichever client makes it; a prompt only tells the agent which tools to call.
arc's entry for the official MCP Registry is generated as server.json, under the name moi.arc/arc.
Agent Install Matrix
The installer detects which agent tools you have on the machine and drops the arc skill into each one's conventional location, plus a fallback under ~/.config/arc/SKILL.md. Expected targets include Claude Code, Codex, Cursor, Windsurf / Codeium, Cline / Roo, Amp, Gemini CLI / Antigravity, GitHub Copilot, Goose, OpenCode, Trae, Kilo, Augment, Aider, and VS Code's skills folder. Agents you don't use stay untouched.
MCP Behavior
arc also registers an arc entry in Claude Desktop's claude_desktop_config.json that runs arc mcp. The MCP server exposes one tool per operation in the catalog below, with the same argument names and validation as the CLI. Existing MCP servers in the config file are preserved — the installer only adds / updates the arc entry.
Remote MCP for Claude.ai web / mobile
arc mcp --http runs the same 121 tools as a Streamable HTTP MCP server instead of stdio. Combined with a tunnel (cloudflare tunnel, tailscale funnel, ngrok, etc.) it lets the Claude.ai web app, Claude mobile app, and Cursor's remote-MCP feature talk to your local arc.
# Loopback only, generates a random bearer token and prints it
arc mcp --http
# Custom port + token, ready to expose via tunnel; tag calls for approvals
arc mcp --http --port 8765 --token $(openssl rand -hex 32) --agent claude-web
# Tunnel it (example with cloudflare quick tunnel — no account needed)
cloudflared tunnel --url http://127.0.0.1:8765
# → https://random-words.trycloudflare.com
Then in Claude.ai → Settings → Connectors → Add custom connector:
- URL:
https://random-words.trycloudflare.com/mcp - Authorization header:
Bearer <token>
The remote server keeps the same withRealClient cache + 90s idle timeout, so a chat conversation pays the connect cost once and subsequent tool calls are instant.
Security:
- Bearer token is required for any non-loopback bind. Constant-time compared to defeat timing probes.
- Default bind is
127.0.0.1— pass--host 0.0.0.0only when intentionally exposing. - The token is printed on stderr at startup; redirect or capture it.
- Anyone with the URL + token gets full read and write access to the budget. Treat the token like the Actual API key. On a paired machine their calls still go through your approvals;
--agentnames them (defaultremote).
Runtime
- Installed app snapshot:
~/.arc-cli/app - Installed config:
~/.arc-cli/config.json(on a paired machine it holds no secrets: those live in the Keychain / Secret Service, servicearc-cli) - Agent activity journal:
~/.arc-cli/activity.jsonl(this machine only) - Launcher:
~/.local/bin/arc - Switch budgets later with
arc budgets switch --budget <id> arc uilaunches the TUIarc mcpstarts the stdio MCP server
Sleeping Servers
Managed Arc servers scale to zero, so one that has been idle has to start before it can answer. The first command after a quiet period takes a few seconds longer while that happens.
Arc handles this for you — every command waits for the server and retries while it comes up. If you would rather pay the wait up front, before opening the TUI or running a batch:
arc wake # or: arc server wake
arc wake --timeout 120
Staying Up To Date
arc version # what you have installed
arc update --check # is anything newer published
arc update # install it
arc update re-runs the published installer, so it refreshes the app snapshot,
the launcher, the agent skill files and the Claude Desktop MCP entry in one go.
Your config and credentials are left alone (in ~/.arc-cli/config.json, or in
the Keychain / Secret Service on a paired machine) — only ~/.arc-cli/app is
replaced. Updating never pairs a machine or moves its secrets.
Restart any running arc mcp server afterwards so it picks up the new tools.
If GitHub is unreachable, the equivalent manual command is the install one-liner above; running it again is always safe.
Security Notes
- macOS-first installer (Linux works for the CLI; the Claude Desktop merge step is a no-op elsewhere).
--pairinstall commands carry only a short-lived pairing token; credentials arrive sealed to this machine after you approve it with Face ID.- Payload install commands (
--payload) embed credentials. Only run them on trusted machines. - Custom reverse-proxy headers are treated like passwords, and are only ever sent to the configured Actual server's origin.
- On a paired machine the Actual password and per-budget encryption passwords live in the macOS Keychain or the Linux Secret Service, not in
config.json; pairing moves them there. Unpaired installs keep them where they always were, so updating changes nothing until you pair. With no Secret Service (a headless Linux server), they stay inconfig.jsonand arc says so once. - Agent Controls stops agents from doing what you did not allow through arc's CLI, MCP and TUI. It does not stop a hostile program running as you from reading the Keychain directly.
Commands
Arc exposes the commands below both as CLI subcommands and as MCP tools (arc mcp). Every entry is generated from the single operation registry, so the CLI, MCP, and docs always match.
Approvals. On a machine paired with the arc app (arc auth pair), each operation is checked against the permissions you set on your phone. Under the default Standard preset, reads run and every change asks first: the agent waits while your phone shows the request, and it runs once you approve with Face ID. Each entry below is tagged with what it does under Standard. Installs set up with the app's payload command (not paired) run everything and keep a local log only.
Accounts
Manage on- and off-budget accounts and balances.
-
arc accounts list— List all accounts in the active budget with balances and on/off-budget status. Approval: runs.arc accounts list -
arc accounts balance— Show the current balance of a single account. Approval: runs.arc accounts balance --account 'HDFC Checking' -
arc accounts create— Create a new account, optionally off-budget and with a starting balance. Approval: asks.arc accounts create --name 'Brokerage' --type investment --offbudget true -
arc accounts update— Update an account's name, type, or on/off-budget flag. Approval: asks.arc accounts update --id 'Cash' --name 'Wallet' -
arc accounts close— Close an account, optionally transferring its remaining balance to another account. Approval: asks · destructive.arc accounts close --id 'Old Card' --transfer-to 'New Card' -
arc accounts reopen— Reopen a previously closed account. Approval: asks.arc accounts reopen --id 'Old Card' -
arc accounts reconcile— Reconcile an account against the bank balance, as Actual's 'Done reconciling' does. Refuses, writing nothing, while the cleared balance differs from the bank and reports the difference. Once they agree, it locks every cleared transaction as reconciled and stamps the account's last-reconciled time. Approval: asks · destructive.arc accounts reconcile --account 'Chase Checking' --balance 1240.55 -
arc accounts delete— Permanently delete an account. Destructive — prefer close in most cases. (advanced) Approval: asks · destructive.arc accounts delete --id 'Test Account'
Transactions
Create, update, split, transfer, and batch-process transactions.
-
arc transactions list— List transactions for an account, optionally filtered by date range. Pass--tagto search across ALL accounts by tag (--accountbecomes optional and narrows results when set). Approval: runs.arc transactions list --account 'HDFC Checking' -
arc transactions add— Add a single transaction to an account. Generates a deterministic imported_id when omitted. Approval: asks.arc transactions add --account 'Card' --date 2026-04-10 --amount -25.50 --payee 'Coffee Shop' --category 'Dining' -
arc transactions import— Bulk-import transactions into an account from a JSON array, with automatic de-duplication. Approval: asks.arc transactions import --account 'Card' '[{"date":"2026-04-01","amount":-1234,"payee_name":"Amazon"}]' -
arc transactions update— Update fields on an existing transaction by id. Use--add-tag/--remove-tagto mutate#tagtokens in notes without rewriting the prose. Approval: asks.arc transactions update --id <txn-id> --category 'Groceries' --notes 'Weekly run' -
arc transactions delete— Delete a transaction by id. Approval: asks · destructive.arc transactions delete --id <txn-id> -
arc transactions split— Create a split transaction with one or more child sub-transactions. Approval: asks.arc transactions split --account 'Card' --date 2026-04-01 --payee 'Costco' --subs '[{"amount":-50,"category":"Groceries"},{"amount":-20,"category":"Household"}]' -
arc transactions transfer— Create a linked transfer between two accounts. Approval: asks.arc transactions transfer --from 'Checking' --to 'Savings' --amount 500 --date 2026-04-10 -
arc transactions refund— Mark a transaction refunded: zeroes its amount and records the original in a#refundnote token, so the row stays visible instead of being deleted. Refuses transfers, splits and reconciled rows. Approval: asks.arc transactions refund --id <transaction-id> -
arc transactions unrefund— Undo a refund, restoring the original amount, its direction (expense or income), and the note. Approval: asks.arc transactions unrefund --id <transaction-id> -
arc transactions refunds— List refunded transactions with the original amount recovered from the refund token, and when each was marked. Approval: runs.arc transactions refunds -
arc transactions duplicates— Find transactions that look like the same purchase recorded twice: same account, same sign, dated within a couple of days, with a matching amount and merchant (or an FX estimate next to the bank's posting). Returns groups with a 0-100 score and the reasons. Transfers and split legs are never flagged. Approval: runs.arc transactions duplicates -
arc transactions batch-update— Apply field updates to many transactions in one call. Accepts a JSON array of {id, ...fields}. (advanced) Approval: asks · destructive.arc transactions batch-update '[{"id":"...","category":"Dining"},{"id":"...","notes":"vacation"}]' -
arc transactions batch-add— Bulk-add transactions to an account, resolving category names and generating imported_ids. (advanced) Approval: asks · destructive.arc transactions batch-add --account 'Card' '[{"date":"2026-04-01","amount":-12.5,"payee_name":"Bakery"}]' -
arc transactions batch-categorize— Categorize all uncategorized transactions in an account whose payee matches a substring pattern. (advanced) Approval: asks · destructive.arc transactions batch-categorize --account 'Card' --payee 'starbucks' --category 'Dining'
Categories
Manage category groups and individual categories, and the sinking-fund savings targets (#template … by YYYY-MM + #goal) Actual keeps in each category's note.
-
arc categories list— List all category groups and their categories. Approval: runs.arc categories list -
arc categories create— Create a new category inside an existing category group. Approval: asks.arc categories create --name 'Coffee' --group 'Food' -
arc categories update— Rename a category, move it to a different group, or toggle hidden. Approval: asks.arc categories update --id 'Coffee' --group 'Dining' -
arc categories templates— List categories whose note carries Actual budget templates (#template/#goal), with the sinking-fund savings target arc can edit and whether the note is editable from arc. Amounts are integer minor units. Approval: runs.arc categories templates -
arc categories template-set— Set a sinking-fund savings target on a category: writes#template <amount> by <YYYY-MM> [repeat every …]plus a#goal <amount>line into the category note, exactly as the arc app's Savings target editor does. Other lines in the note are kept byte-for-byte. Refused when the note holds a template arc will not rewrite (prioritized, several sinking templates, or a non-sinking form) — edit those in Actual. Approval: asks.arc categories template-set --category 'Gifts' --target 500 --by 2026-12 --repeat-months 12 -
arc categories template-clear— Remove the sinking-fund savings target arc manages from a category note (its#template … byline and the#goalline directly beneath). Prose and every other directive are left byte-for-byte. Approval: asks.arc categories template-clear --category 'Gifts' -
arc categories group-create— Create a new category group. Approval: asks.arc categories group-create --name 'Travel' -
arc categories group-update— Rename a category group or toggle it hidden. Approval: asks.arc categories group-update --id 'Travel' --name 'Trips' -
arc categories delete— Delete a category, optionally transferring its transactions and budget to another category. (advanced) Approval: asks · destructive.arc categories delete --id 'Old' --transfer-to 'New' -
arc categories group-delete— Delete a category group and its categories, optionally moving their transactions and budget to a category in another group. (advanced) Approval: asks · destructive.arc categories group-delete --id 'Old group' --transfer-to 'Groceries'
Payees
Manage payees, merge duplicates, and look up usage.
-
arc payees list— List all payees. Pass --all to include hidden / system payees. Approval: runs.arc payees list -
arc payees create— Create a new payee by name. Approval: asks.arc payees create --name 'Local Bakery' -
arc payees update— Rename an existing payee. Approval: asks.arc payees update --id 'Bakery' --name 'Local Bakery' -
arc payees find-or-create— Look up a payee by name and create it if missing. Returns the payee id. Approval: asks.arc payees find-or-create --name 'Local Bakery' -
arc payees common— List the most frequently used payees, ordered by transaction count. Approval: runs.arc payees common --limit 10 -
arc payees delete— Delete a payee. Linked transactions become payee-less. (advanced) Approval: asks · destructive.arc payees delete --id 'Old Vendor' -
arc payees merge— Merge one or more payees into a target payee. Comma-separated source list. (advanced) Approval: asks · destructive.arc payees merge --target 'Amazon' --merge 'AMZN,Amazon.com,Amzn Mktp'
Tags
Manage Actual Budget tags (color, description) and apply / unapply them on transactions. Tag membership lives in transaction notes as #tag.
-
arc tags list— List all tags with their colors and optional descriptions. Approval: runs.arc tags list -
arc tags add— Create a new tag. The leading#is optional and stripped if present. Approval: asks.arc tags add --name Quantini -
arc tags update— Rename a tag, change its color, or update its description.--idaccepts the tag name or its UUID. Approval: asks.arc tags update --id Quantini --color '#FF6B6B' -
arc tags apply— Append one or more tags to a transaction's notes. Comma-separated for multi-tag. Idempotent. Approval: asks.arc tags apply --transaction <tx-id> --tag Quantini -
arc tags unapply— Remove one or more#tagtokens from a transaction's notes. Approval: asks.arc tags unapply --transaction <tx-id> --tag Quantini -
arc tags delete— Soft-delete a tag from the tag library. Existing transactions retain the#tagtext in their notes — you must remove those separately. (advanced) Approval: asks · destructive.arc tags delete --id Quantini
Rules
Define and maintain auto-categorization and payee-cleanup rules.
-
arc rules list— List all transaction rules in the active budget. Approval: runs.arc rules list -
arc rules create— Create a rule from a JSON payload. Account/category/payee names in conditions and actions are auto-resolved to ids. Approval: asks.arc rules create '{"stage":"pre","conditionsOp":"and","conditions":[{"field":"payee","op":"is","value":"Starbucks"}],"actions":[{"field":"category","op":"set","value":"Dining"}]}' -
arc rules update— Update an existing rule. The JSON payload must include the rule id. Approval: asks.arc rules update '{"id":"...","actions":[...]}' -
arc rules delete— Delete a rule by id. Approval: asks · destructive.arc rules delete --id <rule-id>
Schedules
Manage recurring schedules and post them as transactions.
-
arc schedules list— List all recurring schedules. Approval: runs.arc schedules list -
arc schedules create— Create a recurring schedule from a JSON payload. Account/category/payee names are auto-resolved. Approval: asks.arc schedules create '{"name":"Rent","account":"Checking","payee":"Landlord","amount":-150000,"date":{"start":"2026-05-01","frequency":"monthly"}}' -
arc schedules update— Update an existing schedule by id with a JSON payload of fields to change. Approval: asks.arc schedules update --id <sched-id> '{"amount":-160000}' -
arc schedules delete— Delete a schedule by id. Approval: asks · destructive.arc schedules delete --id <sched-id> -
arc schedules post— Materialize a schedule as a real transaction on the given date (defaults to next due date). Approval: asks.arc schedules post --id <sched-id> -
arc schedules upcoming— List schedules sorted by next due date. Approval: runs.arc schedules upcoming -
arc schedules complete— Mark a schedule as completed so it stops generating new occurrences. Approval: asks.arc schedules complete --id <sched-id>
Budgets
Inspect budget months, set budgeted amounts, and switch between budgets.
-
arc budgets list— List budget files available on the configured Actual server. Approval: runs.arc budgets list -
arc budgets months— List the budget months Actual has data for. Approval: runs.arc budgets months -
arc budgets month(alias:show) — Show the full budget for a single month (categories, budgeted, spent, balance). Approval: runs.arc budgets month --month 2026-04 -
arc budgets set-amount— Set the budgeted amount for a category in a given month. Approval: asks.arc budgets set-amount --month 2026-04 --category 'Groceries' --amount 600 -
arc budgets set-carryover— Enable or disable budget carryover (rollover) for a category in a given month. Approval: asks.arc budgets set-carryover --month 2026-04 --category 'Travel' --enabled true -
arc budgets transfer— Move budgeted money between two categories within the same month. Approval: asks.arc budgets transfer --month 2026-04 --from 'Dining' --to 'Groceries' --amount 50 -
arc budgets income— Show income categories with budgeted vs received totals for a month. Approval: runs.arc budgets income --month 2026-04 -
arc budgets summary(alias:totals) — Top-line totals for a month: total budgeted, spent, balance, and to-budget. Approval: runs.arc budgets summary --month 2026-04 -
arc budgets switch— Switch the active budget file for subsequent commands. Persists the selection in the credential store. (advanced) Approval: asks.arc budgets switch --budget 'Family Budget'
Query
Read-only reports and ad-hoc Actual queries.
-
arc query spending— Spending summary for a month broken down by category. Approval: runs.arc query spending --month 2026-04 -
arc query accounts(alias:summary) — Account summary report with balances and on/off-budget grouping. Approval: runs.arc query accounts -
arc query uncategorized— List uncategorized transactions, optionally scoped to one account. Approval: runs.arc query uncategorized -
arc query payee— Recent transactions for a single payee across all accounts. Approval: runs.arc query payee --name 'Amazon' --limit 50 -
arc query category— Transactions in a single category, optionally filtered by date range. Approval: runs.arc query category --name 'Groceries' --start 2026-01-01 --end 2026-03-31 -
arc query trends— Per-category spending trend over the last N months. Approval: runs.arc query trends --months 6 -
arc query top(alias:top-categories) — Top spending categories for a month, ranked by amount spent. Approval: runs.arc query top --month 2026-04 --limit 10 -
arc query monthly(alias:monthly-totals) — Income, expenses, and net totals per month for the last N months. Approval: runs.arc query monthly --months 12 -
arc query balance-history— Daily running balance for an account over the last N months. Approval: runs.arc query balance-history --account 'Checking' --months 6 -
arc query monthly-balances— End-of-month balance series for an account over the last N months. Approval: runs.arc query monthly-balances --account 'Checking' --months 12 -
arc query custom— Run a raw Actual query (ActualQL JSON). Advanced — for power users only. (advanced) Approval: runs.arc query custom --q '{"table":"transactions","select":["id","amount"]}'
Portfolio
Track investment holdings and trade activity (read-only). Investment data lives in account notes (#investment: / #hold:v1:) and #act:-tagged transactions.
-
arc portfolio list— List holdings across all detailed investment accounts (symbol, asset class, quantity, price, value, unrealized P/L %). Approval: runs.arc portfolio list -
arc portfolio holding— Detail for one holding — quantity, price, average cost, market value, unrealized P/L, allocation %, plus its trade ledger. Approval: runs.arc portfolio holding --symbol AAPL -
arc portfolio trades— Trade / activity ledger (buys, sells, fees, dividends, …) across investment accounts and their paired cash accounts. Approval: runs.arc portfolio trades --symbol AAPL -
arc portfolio summary— Portfolio totals — total market value, total unrealized P/L, and allocation by account and by asset class. Approval: runs.arc portfolio summary -
arc portfolio accounts— List investment accounts with their kind (stock/crypto), tracking mode (simple/detailed), data source, and value. Approval: runs.arc portfolio accounts -
arc portfolio realized— Realized P/L from the app's closed-trade history (#trades:v1 notes) — win/loss stats, profit factor, and net realized by symbol, by month or year, and by account. Approval: runs.arc portfolio realized -
arc portfolio dividends— Dividends received, from the app's dividend history (#divs:v1 notes) — every payment plus totals by symbol, by year, and by account. Approval: runs.arc portfolio dividends -
arc portfolio history— Daily portfolio value series from the app's month-sharded position history (#pfhist:v1 notes), summed across accounts, with per-account latest value and top movers. Approval: runs.arc portfolio history
Goals
Savings goals. A goal is an ordinary account whose note carries a #goal: tag, so goals created here appear in the arc app and vice versa. Amounts are integer minor units.
-
arc goals list— List savings goals with funded amount, target, percent complete, and status (on_track / behind / ahead / completed / overdue). Approval: runs.arc goals list -
arc goals show— Full progress for one goal: funded, remaining, days and months left, and the monthly amount needed to stay on track. Approval: runs.arc goals show --goal 'Japan trip' -
arc goals create— Turn an existing account into a savings goal. Writes a#goal:tag onto the account note, so the goal shows up in the arc app too. Approval: asks.arc goals create --account 'Savings' --target 5000 --deadline 2027-03-01 -
arc goals update— Change a goal's name, target, deadline, behavior, color, or icon. Approval: asks.arc goals update --goal 'Japan trip' --target 6000 -
arc goals contribute— Record a contribution against a set-aside goal. Rejected for have-balance goals, which measure the account balance directly — add a transaction to the account instead. Approval: asks.arc goals contribute --goal 'Japan trip' --amount 250 -
arc goals current— Spotlight one goal as the current goal, or clear the spotlight. At most one goal is current at a time. Approval: asks.arc goals current --goal 'Japan trip' -
arc goals archive— Archive a goal. It stops appearing ingoals listbut keeps its data, and loses the current-goal spotlight. Approval: asks.arc goals archive --goal 'Japan trip' -
arc goals reopen— Un-archive a goal. Approval: asks.arc goals reopen --goal 'Japan trip' -
arc goals delete— Remove the goal overlay from an account. The account, its balance and its transactions are left untouched. (advanced) Approval: asks · destructive.arc goals delete --goal 'Japan trip'
Debts
Credit cards, loans and BNPL plans as the arc app (1.0.49+) follows them: each a cycle with a due date, amount due, minimum and state (paid / part paid / unpaid / overdue), plus payoff maths and the "Pay here first" plan. A debt's details live in its account note as one #debt| line, and statement figures in an arc-debt-cycles:<account> note, so what you set or record here shows on the phone and vice versa. Cards in another currency are judged in their own currency.
-
arc debts list— List every debt — credit cards, loans and BNPL plans, tagged or found by account type — with this cycle's state as the arc app judges it: due date, amount due (statement or derived), minimum, paid, left, overdue days, limit and utilisation, rate, autopay and the on-time streak. Also returns overdrawn accounts (kept out of debt totals) and totals: owed, interest and fees this month/year, paydown pace and the debt-free month. Most urgent first. Approval: runs.arc debts list -
arc debts show— One debt in full, as the arc app's card/loan detail shows it: its details (#debt|tag), the cycle being judged (window, amount due and its source, minimum, paid, left, state, days past due, late-reporting days for its region), the last 12 cycles as dots with on-time and in-full streaks, progress (paid off, down this month, pace), interest and fees, limit and utilisation, payoff at the current payment, a loan's position against its schedule, the suggested interest split of the latest instalment, which account to pay from, milestones reached, and the stored cycle records. Approval: runs.arc debts show --account 'HDFC Card' -
arc debts set— Mark an account as a card, loan or BNPL plan, or change any of its details: due day, statement day, credit limit, rate, minimum rule, autopay, region, currency, promo end, and a loan's or plan's schedule (instalment, start, term, principal, count, spacing, first date). Only the fields passed change; every other field (including ones a newer arc wrote) and every other line of the account note are kept. Writes the#debt|line the arc app reads for its cycle, reminders and payoff. Amounts are major units of the debt's own currency. Approval: asks.arc debts set --account 'HDFC Card' --due 5 --statement-day 18 --limit 300000 --rate 42 --min '5%/200' -
arc debts clear— Stop treating an account as a debt: removes the#debt|line from its note. The account, its balance, its transactions and its cycle records are untouched. Approval: asks.arc debts clear --account 'Amex' -
arc debts record— Keep a statement's figures on a debt's cycle (the arc app'sarc-debt-cycles:<account>note): statement balance, minimum due, due date, statement date, credit limit, available limit, and optionally previous balance, interest, fees, and a loan's outstanding/principal/interest. Decimals in the debt's own currency. Merged field by field — typed beats import beats capture — so pass source 'import' for figures read from a statement file. With no due date, the figures go under the due date after the statement date (the tag's due day). The cycle's amount due and minimum then come from these figures. Approval: asks.arc debts record --account 'HDFC Card' --balance 48210 --minimum 2410 --due-date 2026-12-05 --statement-date 2026-11-18 -
arc debts mark-paid— "Already paid? Mark as paid": records that a cycle is paid whatever the rows say (paid from an account arc doesn't track, say), or takes the mark back with undo. Defaults to the cycle being judged now. Approval: asks.arc debts mark-paid --account 'HDFC Card' -
arc debts payoff— Payoff maths for one debt, by the arc app's rules (interest monthly on what's owed, charged before the payment): months and interest at the current payment (minimum, rule, instalment or an estimate) or a payment you give, what an extra each month saves, and what a one-off lump saves — keeping the instalment (ends sooner) or keeping the end month (instalment drops). Amounts in and out are the debt's own currency; inputs in major units, results in minor units. Approval: runs.arc debts payoff --account 'HDFC Card' -
arc debts plan— "Pay here first": which debt spare money should go to. Every debt pays its minimum each month and what a cleared debt was paying rolls on to the next. Avalanche (highest rate first; needs every rate) and snowball (smallest first), each with the first debt, the order they clear, months, total interest and the debt-free month. Minimums that had to be estimated are flagged. Budget currency. Approval: runs.arc debts plan
Statements
The statements the arc app (1.0.50+) files for each account: their figures, whether each reconciled with the bank, the undo journal, the statement and due days learned from them, the payment due on a card, and the fees of the last 12 months with the late fees worth asking back. They live in an arc-statements:<account> note, so what the phone filed reads here. Filing a statement and statement passwords stay on the phone; from here you can switch auto-filing per account, dismiss a fee suggestion, and undo the newest filing exactly as the phone does. Amounts are minor units of the statement's currency, signed as Actual stores the balance (a card that owes is negative).
-
arc statements list— Every account the arc app keeps statements for: how many are filed, the newest one's end date and closing balance and whether it matched the bank's balance (or by how much it was off), whether statements file on their own, the statement and due days learned from them, a statement that should have arrived and hasn't, and for a card the payment due on its newest statement (what it asked, what's left after payments since, the due date, whether the grace period was lost, and the account it was paid from last time). Payments due first. Approval: runs.arc statements list -
arc statements show— One account's statements in full: each statement's period, opening and closing balance, interest and fees, where it came from (filed, typed, read from a text), whether it reconciled with the bank and by how much it was off, and its undo journal (rows it added, cleared, locked, updated or linked, and what Undo filing on the phone would take back or keep because it changed since). Also the cycle learned from them, the next 12 statement and due dates with the annual fee, promo end and last loan instalment, the card fields arc filled in, the foreign-purchase markup, a loan's next instalments, the payment due, and the fees of the last 12 months. Approval: runs.arc statements show --account 'HDFC Card' -
arc statements cycle— The card's cycle as arc learned it from its statements: the statement day, how the due date follows it (a day of the month, or a number of days after the statement) and what the bank does when that lands on a weekend. Then the next 12 cycles (statement date, due date, and the due date before a weekend moved it), the annual fee, promo end and last loan instalment it learned, the card fields it filled in, and the card's usual markup on foreign purchases. Empty until two statements agree. Approval: runs.arc statements cycle --account 'HDFC Card' -
arc statements fees— Fees from the last 12 months, summed from the account's own rows (tax on them apart), and the late fees worth asking the bank to take back: in India a late fee charged when the payment arrived 1-3 days after the due date (RBI), and anywhere the first late fee in a year on a card paid in full since. A fee the bank already reversed, or one you dismissed, is left out. Only accounts with a statement filed; a card's or loan's 12-month total is inarc debts show. Omit the account for every account. Approval: runs.arc statements fees -
arc statements auto-file— Turn statement filing on or off for one account (Settings › Statements on the phone). On, a statement that adds up files itself with no tap; off, it waits on the phone for a look. The switch lives in the budget, so every phone on it follows. Changes nothing else: no rows, no statements. Approval: asks.arc statements auto-file --account 'HDFC Card' --off -
arc statements dismiss-fee— "Not this one": stop suggesting that a late fee is worth asking the bank to take back, on every phone. Only a feearc statements feessuggests now can be dismissed; the fee row itself is not touched. Approval: asks.arc statements dismiss-fee --account 'HDFC Card' --fee <transaction-id> -
arc statements undo— "Undo filing" for the newest statement filed on an account, as the phone does it: unlocks the rows it reconciled, unlinks transfers it made with rows you already had (they get their own payee and category back), deletes the rows it added, takes off the cleared marks it set, puts foreign purchases back to the amount before, then takes the statement off the record. Rows you changed since filing are kept and counted. Only the newest filing: an older one has a newer statement after it. Check first witharc statements show(itsundopreview). Approval: asks · destructive.arc statements undo --account 'HDFC Card'
Group Splits
Share a transaction with other people and track what they owe you. Two kinds live in a budget: #gsplit| tokens in transaction notes (a virtual overlay — no money moves, and balances, registers and reconciliation are untouched), and the arc app's IOUs ledger (1.0.49+), one on-budget account whose rows are what each person owes you or you owe them (read it with ious).
-
arc splits list— List group splits, one entry per split event, with each person's share, what they owe, and whether they have settled. Approval: runs.arc splits list -
arc splits balances— Who owes you what. Totals each person's outstanding and already-settled amounts across every split. Approval: runs.arc splits balances -
arc splits ious— Who owes whom in the IOUs ledger the arc app (1.0.49+) keeps in the budget: one on-budget account (note tag#iou:v1) whose rows are what each person owes you (positive) and what you owe them (negative), with settle-ups and write-offs. Returns each person's balance, their open shares oldest first (payments go to the oldest), totals owed to you and by you, and saved groups. Matches the app's IOUs view: rows from shared arc Splits and balances carried into a Splits thread are left out, since those settle in Splits. Shared Splits threads themselves are sealed on arc's servers and not readable here. Approval: runs.arc splits ious -
arc splits create— Share a transaction with one or more people. Four modes: equal, percent, exact, shares. Records what each person owes without moving any money. Approval: asks.arc splits create --transaction <id> --people 'Sam,Kim' --mode equal --include-self -
arc splits settle— Mark one person's share as paid, optionally linking the repayment transaction so analytics can exclude it from income. Approval: asks.arc splits settle --gid ab12cd --person Sam -
arc splits reopen— Flip a settled share back to open. Approval: asks.arc splits reopen --gid ab12cd --person Sam -
arc splits remove— Drop one person from a split, leaving everyone else in it. Approval: asks · destructive.arc splits remove --gid ab12cd --person Sam -
arc splits delete— Delete an entire split group across every transaction carrying it. The transactions themselves are untouched. (advanced) Approval: asks · destructive.arc splits delete --gid ab12cd
Reconcile
Check a bank statement (CSV or JSON) against an account's transactions: what matches, what the ledger is missing, what the bank never saw, and where the amounts disagree. Uses the same matching as the arc app's statement import, so fuzzy merchant names, posting-date drift and FX estimates line up. Statement amounts are signed from the account holder's side (negative = money out).
-
arc reconcile statement— Compare a bank statement against an account. Each line comes back matched (exact, or a fuzzy merchant/date match), missing from the ledger, an amount mismatch, or ambiguous, and ledger rows in the statement's date range that no line explains come back as extra. Optionally checks the opening and closing balances. Changes nothing. Approval: runs.arc reconcile statement --account 'Chase Checking' --file ~/Downloads/may.csv -
arc reconcile apply— Apply a statement: import the lines the ledger is missing (cleared, with a deterministic imported_id so a re-run adds nothing) and mark matched transactions cleared. Amount mismatches and ambiguous matches are reported and left alone. Runarc reconcile statementfirst to see what it will do. (advanced) Approval: asks · destructive.arc reconcile apply --account 'Chase Checking' --file ~/Downloads/may.csv
Server
Server lifecycle. Managed Arc servers scale to zero, so one that has been idle must start before it can answer. Every other command absorbs this automatically; call wake when you would rather pay the wait up front.
-
arc server wake— Start a sleeping server and wait until it answers. Managed Arc servers scale to zero, so the first call after an idle period pays a cold start. Every other tool absorbs this automatically — call this first when you would rather pay the wait in one cheap request than risk it landing on a slow one. Approval: runs.arc server wake
Agent
Agent Controls. On a machine paired with the arc app, every operation is checked against the permissions you set on your phone. These two tools let an agent see those permissions and finish a call that waited for your approval. They are never gated, and no tool can approve or deny anything — that takes your Face ID or Touch ID.
-
arc agent request-status— Finish a call that returnedpending_approval. Waits up towait_secondsfor the user to decide, then runs the exact call they approved, once, and returns its result. Returnspending_approvalagain if they have not decided yet, or an error if they denied it or it expired. Approval: never asks.arc agent request-status --request-id k57abc --wait-seconds 30 -
arc agent permissions— What this agent may do on this machine: for each operation group, whether reads, writes and deletes run, ask the user first, or are refused, plus any time-limited approvals in force. Call it before a batch of changes so you can tell the user what will need their approval. Approval: never asks.arc agent permissions
Dashboard Recipes
arc ships with 13 pre-built dashboard recipes that any AI agent can use to generate beautiful, self-contained HTML financial dashboards from your budget data. Recipes live in skill/recipes/.
| Recipe | Description |
|---|---|
| recipe-spending | Monthly spending breakdown with donut chart and category cards |
| recipe-trends | Month-on-month income vs expense trends with heatmap |
| recipe-budget | Budget vs actual with adherence indicators |
| recipe-accounts | Account overview and net worth |
| recipe-recurring | Recurring payments / subscription tracker |
| recipe-payees | Payee / merchant spending analysis |
| recipe-income | Income report with sources and trends |
| recipe-category | Single-category deep dive over time |
| recipe-balance | Account balance history with daily chart |
| recipe-health | Financial health scorecard (0-100 score) |
| recipe-annual | Full-year summary with quarterly breakdown |
| recipe-uncategorized | Data quality / uncategorized transactions |
| recipe-upcoming | Upcoming payment calendar with coverage |
Creating Your Own Recipes
Recipes are plain Markdown files that tell AI agents how to generate a dashboard. Anyone can create and share recipes — no code required.
Every recipe file follows this structure:
---
name: recipe-my-custom
description: One-line description of what this dashboard shows
---
# Dashboard Title
## Trigger
Phrases that should activate this recipe
## Data Commands
Exact arc CLI commands to run with --json flag
## Layout
Component-by-component description, top to bottom
## Design
Color choices, accent colors, special formatting rules
## Empty State
What to show when no data is available
All recipes must use the arc dark editorial theme (near-black background, DM Serif Display + Outfit + JetBrains Mono fonts, arc nav bar with logo). See recipe-spending.md for a complete example.
To contribute a recipe:
- Fork this repo
- Add your recipe-*.md file to skill/recipes/
- Open a PR with a description of the dashboard and a screenshot
To use a custom recipe locally, drop your recipe-*.md file into the arc-dashboard-design skill directory:
- Claude Code: ~/.claude/skills/arc-dashboard-design/
- Cursor: ~/.cursor/skills/arc-dashboard-design/
- Generic: ~/.config/arc/recipes/
No installation packages available.