What is the Candor CLI?
The Candor CLI is a command-line client for Candor, the read-only money workspace your AI agent works in, published on npm as @candorsystems/candor-cli. Terminal agents such as Claude Code, Codex, Gemini CLI, OpenClaw, and Hermes run it to open what's worth talking through, read accounts and transactions, and save the budgets, goals, and notes you set with your agent. It returns Markdown by default and JSON with --json.
Every command describes itself. candor --help lists the commands, candor schema describes the operations, and each response ends with the exact next commands the agent can run, so a capable agent works without a manual.
Most agents connect through Candor's remote MCP server instead. The CLI suits an agent that runs on a machine with a shell, a script, or a host where MCP is not available. Both open the same workspace.
How does an agent set up the Candor CLI?
The agent installs the CLI from npm and runs candor setup. Setup opens your browser to approve the agent, choose a plan, and connect accounts through bank-grade secure sign-in. Your bank login never passes through the agent. candor doctor then checks the local setup without reading any financial data.
candor skill install adds the candor-finance skill, which teaches the agent the methods: checking coverage before quoting a total, investigating a possible duplicate charge, keeping a saved budget current. candor skill update keeps it on the version the CLI expects.
On macOS and Linux, the CLI stores its sign-in in a credential file only your user can read, so scheduled runs work unattended. Set CANDOR_CLI_CREDENTIAL_STORE=keyring to use the system keyring instead. Windows uses the native credential store.
npm install --global @candorsystems/candor-cli candor setup candor skill install candor doctor
What does candor open show an agent?
candor open returns what changed since the agent last looked, your financial position, saved budgets, goals, and notes, and the latest weekly review. Every week Candor reviews your records and notes and raises up to five areas worth talking through and up to three gaps worth filling, each with the records behind it and no figures. When nothing matters, it raises nothing.
The review covers what a careful advisor would raise: a price increase, a duplicate charge, idle cash while a card charges interest, budget drift, changed income, a debt deadline, goal pace, and questions such as an employer match left on the table. candor reviews update records what came of each item, which the next review reads. candor reviews list returns earlier weeks' reviews, with what came of each item.
Once the agent has worked through the opening, candor open acknowledge marks that activity as seen, so the next session starts from what is new. Candor is not a licensed advisor: the agent makes suggestions and you decide.
candor open candor reviews update --file OUTCOME.json candor reviews list
Which commands do agents use most?
After candor open, agents mostly use candor transactions list, candor budget status, candor recurring list, candor goals list, and candor notes create. Each read and write takes a --reason, which Candor records with the action, so you can see why your agent looked. Run candor --help for the full list.
Totals, budget pace, and variance are computed from your records, so the agent reports a figure instead of predicting one. Responses carry how fresh the data is and what may be missing, and figures on a paged read cover exactly the records it returns.
candor transactions list --limit 25 --reason "Check this month's dining spend" candor budget status --reason "Check budget pace before Friday" candor recurring list --reason "Review recurring charges for price changes" candor notes create --file NOTE.json --reason "Record the decision to cancel the duplicate plan"
Which agents use the Candor CLI?
Any agent that can run a shell: Claude Code, Codex, Gemini CLI, OpenClaw, Hermes, and scripts you write. Claude Code and Codex usually install Candor's plugin, which connects through remote MCP; OpenClaw uses MCP with the CLI as a fallback. Whichever route an agent takes, it opens the same workspace, so plans made in one agent are there in the next.
The CLI can run on a schedule through the agent's own scheduler or a cron job. Scheduling belongs to the agent or the host, not to Candor.
Can the Candor CLI move money?
No. The Candor CLI has no command to move money, pay a bill, trade, or cancel a service. It reads records, computes figures, and saves workspace state from what you tell your agent, such as budgets, goals, and notes. Anything outside Candor, the agent does through its own tools with your approval.
Candor never sells your data or trains models on it. You can export or delete what Candor holds, and revoke an agent's access, from your account.
Common questions
- Can I use the Candor CLI as a personal finance agent builder?
- The CLI is a way for an agent or script to work in Candor. It provides access to financial records, calculations, and saved workspace state. You supply the agent, its instructions, and any scheduling or external tools. Candor does not execute payments or trades.
- Should my agent use the Candor CLI or MCP?
- Let the agent follow its own setup route. Claude Code and Codex install Candor's plugin with remote MCP; Claude, ChatGPT, Grok Bot, and Muse use remote MCP. Use the CLI when the agent runs on a machine with a shell and MCP is not available, or for scripts. Both open the same workspace.
- Does the Candor CLI return JSON or prose?
- Markdown by default, written for an agent to read, with exact statuses and next commands kept. Add --json for the full machine-readable response when a script needs it.
- Where does the Candor CLI keep its credentials?
- On macOS and Linux, in a credential file readable only by your user, so scheduled runs work unattended; set CANDOR_CLI_CREDENTIAL_STORE=keyring for the system keyring. Windows uses the native credential store. Bank logins are never stored by the CLI.
- Can the Candor CLI run on a schedule?
- Yes, through your agent's scheduled tasks or a cron job on the host. Scheduling belongs to the agent, not to Candor. A scheduled run can open the workspace, check what's worth talking through, and message you only when something does.
- Can the Candor CLI connect bank accounts?
- Only through the browser. candor setup hands off to Candor's web app, where you connect accounts through bank-grade secure sign-in. The CLI never handles bank credentials.