--- title: "Candor CLI: Personal Finance for Terminal AI Agents | Candor" description: "The Candor CLI lets terminal agents like Claude Code, Codex, and OpenClaw work in Candor: what's worth talking through, saved plans, read-only access." url: "https://candor.money/candor-cli-for-ai-agents" updated: "2026-10-19" --- # A CLI built for agents, not dashboards. Updated 2026-10-19. Canonical page: https://candor.money/candor-cli-for-ai-agents The Candor CLI is how an agent with a shell works in Candor. One command opens Candor's weekly review: the areas worth talking through and the gaps worth filling, with the records behind each item. Others pull the exact transactions, budgets, and goals a question needs, and save what you settle on with its reason. Output is Markdown an agent reads well, or JSON for scripts. Nothing in it can move money. ## How it works with your agent 1. Your agent installs the CLI and runs candor setup. You approve its access in the browser, choose a plan, and connect accounts through bank-grade secure sign-in. 2. candor open returns what changed since the agent last looked, the budgets and goals saved from what you tell your agent, and what's worth talking through. 3. The agent pulls the records a question needs, with the figures computed from them, and loads the finance skill for the method. 4. What you settle on with your agent is saved in Candor with its reason, so the next session, or a different agent, starts from it. ## 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. - [The Candor Finance MCP server](https://candor.money/mcp) ## 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. ```text 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. ```text 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. ```text 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. - [Connect Claude Code](https://candor.money/connect/claude-code) - [Connect Codex](https://candor.money/connect/codex) - [Connect OpenClaw](https://candor.money/connect/openclaw) - [Candor's MCP server](https://candor.money/mcp) ## 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. - [Read-only finance access for AI agents](https://candor.money/read-only-finance-ai) ## 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. ## Keep reading - [Personal finance MCP servers compared](https://candor.money/personal-finance-mcp-servers) - [How to use AI to analyze your finances](https://candor.money/how-to-use-ai-to-analyze-your-finances) - [The AI financial review](https://candor.money/ai-financial-review) - [The AI personal finance agent](https://candor.money/ai-personal-finance-agent) - [Where do I actually stand?](https://candor.money/explore/first-pass) - [Can you keep my money organized for me?](https://candor.money/explore/organize) ## Let your terminal agent run the first check-in. Send your agent the Candor setup message and approve access in your browser. It can then open the workspace, investigate what's worth talking through, and keep your decisions. Agents can install Candor themselves from https://candor.money/START.md.