What is the Candor CLI?
The Candor CLI is a command-line client for the Candor financial workspace, published on npm as @candorsystems/candor-cli. Terminal agents such as Claude Code, Codex, Gemini CLI, OpenClaw, and Hermes run it to open what needs a decision, read accounts and transactions, and save approved budgets, goals, and notes. 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 an approved 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, approved budgets, goals, and notes, and what needs a decision. Candor reviews your records whenever they change and keeps that list short, each item with its figures and the reason it made the list. If nothing qualifies, it is empty.
The list 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 conversations get returns the full list with the figures behind 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 conversations get
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 you approve, 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
- 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 needs a decision, 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.