Skip to main content
The CLI is the npm package @conto_finance/create-conto-agent. It provides the create-conto-agent and conto commands. Run it with npx to start the setup wizard:
Or install it globally:
The examples on this page use conto, which the global install provides. Without a global install, run npx @conto_finance/create-conto-agent <command>, or npx conto <command> inside a project the CLI set up. The unscoped npm package named conto is not the Conto CLI.

Init wizard

--chain expects the chain ID returned by GET /api/chains, for example 42431, 4217, 8453, or solana-mainnet. If it is omitted in a headless run, setup uses Tempo Testnet (42431). --api-key is also accepted, but CONTO_ORG_API_KEY avoids placing the key in process arguments.
The interactive wizard needs a terminal and a browser. For CI, scripts, and autonomous agents, use a noninteractive mode instead. The wizard runs these steps:
1

Configure your agent

Choose your agent name, type, daily spending limit, and network.
2

Authenticate in the browser

The CLI opens a browser window to conto.finance/cli-auth. Sign in with your Conto account (or create one). The browser sends the token and its expiration time back to the CLI automatically. Browser-issued organization credentials expire after seven days. Resetting your Conto password revokes them. Run conto login again to renew one.
3

Create the agent and wallet

The wizard creates a wallet on your chosen chain, registers the agent, links the wallet with spend limits, creates a default spending policy, and generates an SDK key.
4

Save your project files

The wizard writes or updates four files in your current directory:
  • .env.local: SDK key and configuration (owner-only permissions)
  • .gitignore: updated to ignore .env.local
  • conto.config.json: agent metadata
  • example.mjs: runnable payment example
In an existing .env.local, setup replaces every CONTO_* key and keeps all other lines and comments. If conto.config.json or example.mjs already exists with other content, the wizard asks before replacing it. A headless run keeps the file and lists it under keptFiles in its JSON output. Pass --overwrite to replace both without asking.It also adds @conto_finance/create-conto-agent as a dev dependency, creating a minimal package.json if the directory has none. Pass --no-install to skip this.

Supported networks

The wizard lists every chain returned by /api/chains, including Ethereum, Arbitrum, Polygon, Base Sepolia, and Solana Devnet. The first run defaults to Tempo Testnet, so evaluation cannot move real funds.
Choosing any mainnet prompts for confirmation. Headless setup must include --confirm-mainnet together with an explicit mainnet --chain, for example --chain 4217 --confirm-mainnet.

Run the example

The example prints your agent, key scopes, and wallet from GET /api/sdk/setup, then requests a $0.01 payment through the policy engine. Without --execute it stops after the policy decision. Use --resume REQUEST_ID to continue that request, or --execute on the first run to request and execute a new payment together.

Headless and agent runs

For CI, scripts, and autonomous agents, use a noninteractive mode:
Both modes write the same files as the wizard. Sandbox mode also writes the sandbox setup key, which configures that sandbox’s policies and spend limits, to .conto/sandbox-setup.env. Keep that file out of the agent’s runtime. --json prints a machine-readable result to stdout with credential file and environment-variable names, never the credential values. Without a TTY and without one of these modes, the CLI exits with an error that lists them instead of hanging on a prompt. --help and --version work in any terminal, TTY or not. After a headless run:

Resume and exit codes

Organization setup records each step in .conto/init-checkpoint.json before it creates anything. The record holds resource IDs and the requested configuration, never a key. When a step fails, setup stops with "status": "partial", the failed step, the IDs it created, and a resume command. It writes no agent credentials until every step succeeds. --resume checks each recorded resource and creates only what is missing. It refuses a different base URL, organization, or configuration. --restart discards the record. Resources the old setup created stay in the organization.

Global options

All commands support these flags:

Agent and status

conto doctor calls GET /api/sdk/setup with your SDK key and reports each check, including whether the key has payments:request and payments:execute and whether the wallet can execute real transfers. When the server returns setup diagnostics, those decide the result, and each issue says whether the agent or an owner acts next.For anonymous sandbox setups created with create-conto-agent --sandbox, conto doctor treats simulated execution as healthy and reports the sandbox expiry instead of warning that the wallet is manual-only.
conto doctor --json prints exactly one JSON document with ok, exitCode, baseUrl, diagnosticsSource (server or cli), checks, issues, diagnostics, and setup.

Sandbox handoff

Hand an anonymous sandbox to the person who will own it, from a remote or headless shell:
sandbox claim uses only the sandbox organization key, CONTO_SANDBOX_API_KEY, from the environment or .env.local. It returns a verificationUrl. Send that URL only to the person who will own the sandbox, because it holds a temporary secret. The polling token stays in the owner-only .conto/sandbox-claim.json and is never printed. Running sandbox claim again reuses a pending link. claim-status never prints the link. A claim makes that person the owner and revokes the sandbox setup key. The sandbox stays in test mode. A claim does not fund a wallet, change spending limits, grant scopes, or enable live payments. See hand off to a person.

Payments

When a payment needs approval, conto pay prints a review link and opens it in your browser. In a terminal it waits up to 5 minutes for the decision and sends the payment once it is approved. Use --wait <seconds> to wait in scripts, --no-wait to return right away, and --no-open to skip the browser. conto pay status <requestId> picks the payment up later and sends it if an approver approved it meanwhile. For a payment that needed no approval, it only reports the status and sends nothing. Every run sends an idempotency key and prints it before the request, then prints the request ID before it sends the payment. With --json, stdout stays one JSON document, so these two lines go to stderr and both values are also in the JSON result.
A timeout, dropped connection, non-JSON response, or server error can leave a payment sent without a receipt. The command then exits with code 6 and says the outcome is unknown. Do not run the same command again, because that starts a new payment. Run conto pay status <requestId> instead. If the failure came before a request ID was issued, retry the same command with --idempotency-key <key>, which returns the same request instead of creating another.
--dry-run makes no API calls. It checks the address, amount, purpose, and category locally against the same rules the server uses, then prints the POST /api/sdk/payments/request it would send. It runs no policy evaluation, so a valid dry run does not mean the payment will be approved. Run conto limits to see the agent’s current limits.

Transactions

Add --json for the full record, including source wallet, authorization decision, and block details.

Wallets

Wallet controls use your organization login. See Owner review for the commands marked owner review.

Spending limits

A wallet with no limit reads unlimited. With --json, its limit and remaining are null, and its perTransaction is null when it has no per-payment limit.

Shared budgets

These commands manage one limit shared by several agents. Read supported payment paths before creating a budget. Amounts use decimal strings, such as "40.00".
The JSON file for create uses the fields in admin.spending.createBudget(). update also accepts --expires <iso-date> to extend the budget’s end date. Read the budget again before updating it and pass its current version. Pausing stops new purchases; it does not end the budget’s restrictions on other payment paths.

Task approvals

request accepts --merchants <ids...> and --sources <ids...> to limit the task to named recipients and payment sources. decide accepts --amount and --agents <ids...>; the approved agents must include the requester. Listing supports --cursor <cursor> for the next page. Wait for task approval before requesting a payment that requires it.

Purchases against shared budgets

These are shared-budget records, separate from Commerce purchases. Owner actions use the configured organization API key; other actions use the agent’s SDK key. --owner selects the organization key where offered. See permissions and outcome fields. Check status after a timeout before resuming a payment. A preview never authorizes execution, and an unknown outcome must stay held until it is resolved.

Accounting export

Export spend across every payment rail, with categories and GL accounts, for month-end close. An organization key is required. See accounting export.
--output creates a private file and refuses to overwrite an existing one. Without it, the export goes to standard output.

Alerts

ack and resolve use the agent’s SDK key. Alerts about the agent’s own controls are left for a person to handle in the dashboard.

Policies

Run policy commands from a project the CLI set up. They use the organization API key saved during setup. Lists show [organization] for mandatory baselines and the effective assignment path, such as [agent] or [wallet], for assigned policies.
Creating policies and adding rules run at once, because they can only add restrictions. Updating, deleting, unassigning, removing a rule, and rolling back can loosen controls, so with the key from conto login they go to owner review. conto policies all lists every policy in the organization, not only your agent’s, with each policy’s ID, type, priority, rules, and active status.
Organization policies cannot be assigned or unassigned because they already apply to every payment. To stop one, deactivate or delete it. Assigned policies do nothing until linked to an agent, wallet, or card.
All policy commands support --json:

Create a policy

conto policies create walks you through each step with descriptions. It prompts for:
  1. Policy name. A descriptive label.
  2. Policy type. One of the types below, each with an explanation.
  3. Scope. Apply to the entire organization or only explicitly assigned targets.
  4. Priority. Higher numbers are evaluated first. Use 0-100. Default is 50.
  5. Rules. Optionally add the first rule immediately.
  6. Assignment. Assigned policies can be linked to the current agent.
The type only sets which rules the builder offers. Conto evaluates each rule by its rule type, so an allow list works the same under Counterparty, Merchant, or Whitelist.

Add rules

conto policies add-rule <policy-id> prompts for:
  • Rule type: context-aware options based on the policy type
  • Operator: <=, >=, in list, not in list, between, etc.
  • Value: with placeholders that show the format (dollar amounts for limits, JSON arrays for lists, country codes for geographic rules)
  • Action: Allow, Deny, or Require Approval
A bare number for Velocity Limit is a dollar amount per hour, not a transaction count. Use maxCount to limit the number of transactions or maxAmount to limit spend. period is HOUR, DAY, WEEK, or MONTH.

Agents

Teams

Group agents into teams. A team’s policies apply to every agent in it, alongside company policies. Teams need CLI 0.7.0 or later.
Reads work with any organization key. With the key from conto login, every change goes to owner review: the command prints a review link and waits for an owner or admin to confirm it. This needs CLI 0.8.0 or later. A key made in the dashboard under Developers, set as CONTO_ORG_API_KEY, makes the change directly. A manager needs the Manager role or higher. If your organization requires approval for budget changes and a move takes an agent off a budget, the move can’t go through owner review. Make it in the dashboard, or with a dashboard key. With a dashboard key, add and remove exit 4 and nothing changes. Once it is approved, run the same command with --approval <id>.

Payees

Event delivery

A new webhook channel gets a signing secret that the CLI prints once, or uses CONTO_WEBHOOK_SECRET when it is set, without printing it. Add Slack, Telegram, and WhatsApp channels in Settings > Notifications.

Owner review

The key that conto login saves lives on your machine, where an agent running there can read it. So it can only tighten controls: pause, freeze, revoke, block, and lower limits run at once. A change that loosens controls, such as resuming an agent, raising a limit, linking a wallet, creating an SDK key, or changing a team, is sent for review instead:
  1. The CLI prints a review link and opens it in your browser.
  2. An owner or admin signs in and confirms or declines the change.
  3. The CLI waits and reports the outcome. A new SDK key is shown once, in the terminal that asked.
In a terminal the CLI waits up to 5 minutes. Use --wait <seconds>, --no-wait, and --no-open to change that. Follow a change later with:
An organization key made in Developers > API keys and passed as CONTO_ORG_API_KEY makes these changes directly, with no review.
Only put a dashboard-made organization key on a machine you would trust with an owner’s access. An agent that can read it can change its own controls.

Authentication

The login key expires after 7 days and can only tighten controls. See Owner review. An agent key belongs to the server that issued it. Logging in to a different server removes the agent key and the agent, wallet, and network details saved in ~/.conto/config.json, so they never reach the new server. A project’s .env.local stays as it is. Run conto init to set up an agent on the new server.

MCP server

Documentation

JSON mode

Every command supports --json for machine-readable output:

Configuration files

Configuration precedence is process environment, project .env.local, project conto.config.json, then global ~/.conto/config.json. Generated credential files use owner-only permissions, and init adds .env.local to the project .gitignore. Init replaces only the CONTO_* keys in an existing .env.local. The CLI creates .conto/ with owner-only permissions and adds it to .gitignore when it first writes a file there.

Local webhook testing

Set CONTO_WEBHOOK_SECRET to your local handler’s signing secret. The CLI sends a synthetic signed payment event, reports response status and latency, and exits nonzero if delivery fails. This command requires no Conto credentials and accepts only loopback destinations. See webhook testing.

Continue a generated payment example

Save the request ID printed by example.mjs. After owner review or an interrupted run, check or resume that same request instead of starting another payment:
Resume checks the current status and executes only an approved request. A completed, declined, or pending-review request is reported without another execution. Running the example without either option starts a new payment intent.

Save a controlled-payment test report

Use the original request IDs from the same agent, wallet, and currency. The SDK key needs transactions:read and audit:read. This command only reads evidence; it never requests or executes a payment. It writes a new JSON file with owner-only permissions and refuses to overwrite an existing file. The CLI exits 2 if it saves a report with incomplete control or audit evidence. --review is optional; omitting it records reviewCoverage: "not_tested". For a rejection or expiry exercise, use --review-outcome denied or --review-outcome expired. Payment completion, control verification, audit evidence, and file persistence are separate milestones. A simulated receipt does not prove an onchain transfer. Existing denied requests without a recorded wallet remain incomplete evidence; create a new exercise instead of reusing those records.