CLI commands

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:

npx @conto_finance/create-conto-agent

Or install it globally:

npm install -g @conto_finance/create-conto-agent
create-conto-agent

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

create-conto-agent              # Run the setup wizard (interactive)
conto init                      # Same as above

# Non-interactive with flags:
CONTO_ORG_API_KEY=conto_xxx create-conto-agent --base-url https://conto.finance --name my-agent --type ANTHROPIC_CLAUDE --limit 500 --chain 42431 --json

# Mainnet requires an explicit chain and real-funds acknowledgement:
CONTO_ORG_API_KEY=conto_xxx create-conto-agent --chain 4217 --confirm-mainnet

# Skip adding the CLI as a dev dependency:
create-conto-agent --no-install

# Finish an interrupted organization setup, or discard its record and start over:
CONTO_ORG_API_KEY=conto_xxx create-conto-agent --resume --json
CONTO_ORG_API_KEY=conto_xxx create-conto-agent --restart --json

--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:

Configure your agent

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

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. Run conto login again to renew one.

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.

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

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

Network	Currency	Chain ID	Notes
Tempo Testnet	pathUSD	42431	Use for evaluation, auto-funded via faucet
Tempo	USDC.e	4217	Mainnet. Moving real funds needs confirmation
Base	USDC	8453	Mainnet. Moving real funds needs confirmation
Solana	USDC	solana-mainnet	Mainnet. Moving real funds needs confirmation

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

node example.mjs                      # Check setup + request a test payment (no funds move)
node example.mjs --resume REQUEST_ID  # Continue the request printed above

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:

# Anonymous test-mode sandbox: no account, no browser, no prompts.
# Expires after 7 days. Test payments do not submit an onchain transfer.
npx @conto_finance/create-conto-agent --sandbox --json

# Existing organization: authenticate with an org API key instead of the browser.
export CONTO_ORG_API_KEY=conto_xxx
npx @conto_finance/create-conto-agent --name my-agent --json

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:

# Hand the sandbox to the person who will own it. Send them only the verificationUrl.
npx @conto_finance/create-conto-agent sandbox claim --json

# See what the agent can do now, and who acts on each remaining issue.
npx @conto_finance/create-conto-agent doctor --json

# Finish an organization setup that stopped with "status": "partial".
npx @conto_finance/create-conto-agent --resume --json

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.

Exit code	Meaning
0	Setup complete
1	Setup failed before anything was created
2	Refused: unfinished setup, mismatched resume, or rejected credential
3	Partial setup, run the resume command
4	Reconciliation or owner action needed first, see the output

Global options

All commands support these flags:

Flag	Description
`--json`	Output in JSON format for scripting
`--help`	Show help for any command
`--version`	Show CLI version

Agent and status

conto doctor                    # Diagnose setup: auth, scopes, wallet, chain, balance, base URL
conto doctor --json             # One JSON document with the server's setup diagnostics
conto status                    # Agent info, wallet balances, spending progress
conto balance                   # Wallet balance table
conto config                    # Show current configuration
conto config <key> <value>      # Update a config value

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.

Exit code	Meaning
0	No action needed
1	Action required. Each issue names who acts and the next step
2	The check could not complete, for example Conto was unreachable

Sandbox handoff

Hand an anonymous sandbox to the person who will own it, from a remote or headless shell:

conto sandbox claim                          # Create or reuse a claim link for the owner
conto sandbox claim --wait --timeout 300     # Wait until the owner claims it
conto sandbox claim-status                   # pending, claimed, or expired

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.

Exit code	Meaning
0	Link issued or reused, or the sandbox was claimed
1	Request failed
2	Missing or wrong credential, or unusable local claim state
3	The link or the sandbox expired
4	`--wait` timed out and the link is still valid
5	Rate limited, see `retryAfterSeconds`
130	Interrupted while waiting, the link is still valid

Payments

conto pay <address> <amount>                    # Request and execute payment
conto pay <address> <amount> --dry-run          # Validate input and show the request, send nothing
conto pay <address> <amount> --purpose "reason" # Add a purpose string
conto pay <address> <amount> --wallet <id>      # Use a specific wallet
conto pay <address> <amount> --category "API"   # Tag with spend category

--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

conto transactions              # List recent transactions (default: 10)
conto transactions --limit 50   # List more transactions
conto transactions <id>         # View transaction details

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

Wallets

conto wallets                   # List all wallets with balances
conto fund                      # Show chain-aware funding instructions
conto fund --faucet             # Request testnet funds when the configured chain supports it

Spending limits

conto limits                    # Daily/weekly/monthly limits with progress bars

Alerts

conto alerts                    # List all alerts
conto alerts --unread           # Active alerts only (alias for --active)

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.

conto policies                  # List effective policies and their scope/assignment path
conto policies all              # List all org policies
conto policies create           # Interactive policy builder
conto policies update <id>      # Update name, priority, active status
conto policies delete <id>      # Delete with confirmation
conto policies assign <id>      # Assign policy to current agent
conto policies unassign <id>    # Remove policy from agent
conto policies add-rule <id>    # Add a rule to a policy
conto policies remove-rule <policyId> <ruleId>  # Remove a rule

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:

conto policies --json
conto policies all --json
conto policies create --json    # Returns created policy as JSON

Create a policy

conto policies create walks you through each step with descriptions. It prompts for:

Policy name. A descriptive label.
Policy type. One of the types below, each with an explanation.
Scope. Apply to the entire organization or only explicitly assigned targets.
Priority. Higher numbers are evaluated first. Use 0-100. Default is 50.
Rules. Optionally add the first rule immediately.
Assignment. Assigned policies can be linked to the current agent.

Type	Description
Spend Limit	Cap per-transaction, daily, weekly, or monthly totals
Approval Threshold	Require human approval above a dollar amount
Counterparty	Allow or block addresses, or check trust score and trust level. Use this for most payee rules
Category	Restrict which spend categories are permitted
Geographic	Restrict payments by recipient country
Budget Allocation	Set a total budget cap for a time period
Expiration	Deny payments outside a date range
Merchant	The same allow and block lists, labeled as merchants. Use this to keep merchant lists apart from other payees
Time Window	Restrict transactions to specific hours or days
Velocity	Rate limit: max transactions per time period
Whitelist	One allow list. Use this when only listed addresses may be paid
Composite	Mix rule types in one policy. Rules always combine with AND
Contract Allowlist	Restrict to approved smart contract addresses
Blackout Period	Block all transactions during specific time windows

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

Rule Type	Example Value	Format
Daily Limit	`500`	Dollar amount
Allowed Counterparties	`["0xabc...","0xdef..."]`	JSON array of addresses
Geographic Restriction	`["US","CA","GB"]`	JSON array of country codes
Trust Score	`0.7`	Number (0.0-1.0)
Date Range	`{"start":"2026-10-01","end":"2026-12-31"}`	JSON with ISO dates
Velocity Limit	`{"maxCount":5,"period":"HOUR"}`	JSON with `maxCount` or `maxAmount` and `period`
Time Window	`{"start":"09:00","end":"17:00","timezone":"America/New_York"}`	JSON with 24-hour times
Blackout Period	`{"windows":[{"start":"02:00","end":"06:00"}]}`	JSON with a `windows` list

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.

Authentication

conto login                     # Re-authenticate (opens browser)
conto login --base-url <url>    # Authenticate against a specific server
conto logout                    # Clear stored credentials

MCP server

conto mcp                       # Start the Conto MCP server for Claude

Documentation

conto docs                      # Open the CLI quickstart docs
conto docs commands             # Open the commands reference
conto docs policies             # Open the policy docs
conto docs sdk                  # Open the SDK installation guide
conto docs api                  # Open the API reference page

JSON mode

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

conto status --json | jq '.agent.name'
conto pay --dry-run 0x... 10 --json | jq '.valid'
conto policies --json | jq '.[].name'

Configuration files

File	Location	Purpose
`~/.conto/config.json`	Global	API keys, agent ID, server URL
`.env.local`	Project	SDK key, chain config, wallet address
`conto.config.json`	Project	Agent metadata (generated by init)
`.conto/sandbox-setup.env`	Project	Sandbox setup key, kept out of the agent runtime
`.conto/sandbox-claim.json`	Project	Pending sandbox claim link and polling token
`.conto/init-checkpoint.json`	Project	Progress of an unfinished organization setup, no keys

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. The CLI creates .conto/ with owner-only permissions and adds it to .gitignore when it first writes a file there.

Local webhook testing

conto webhooks test http://localhost:8080/webhooks/conto --json

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:

node example.mjs --status REQUEST_ID
node example.mjs --resume REQUEST_ID

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.

Get started

Integrate

Payments

Conto Commerce

Spending controls

Operate

Conto Pay

CLI commands

Init wizard

Supported networks

Run the example

Headless and agent runs

Resume and exit codes

Global options

Agent and status

Sandbox handoff

Payments

Transactions

Wallets

Spending limits

Alerts

Policies

Create a policy

Add rules

Authentication

MCP server

Documentation

JSON mode

Configuration files

Local webhook testing

Continue a generated payment example

​Init wizard

​Supported networks

​Run the example

​Headless and agent runs

​Resume and exit codes

​Global options

​Agent and status

​Sandbox handoff

​Payments

​Transactions

​Wallets

​Spending limits

​Alerts

​Policies

​Create a policy

​Add rules

​Authentication

​MCP server

​Documentation

​JSON mode

​Configuration files

​Local webhook testing

​Continue a generated payment example

Init wizard

Supported networks

Run the example

Headless and agent runs

Resume and exit codes

Global options

Agent and status

Sandbox handoff

Payments

Transactions

Wallets

Spending limits

Alerts

Policies

Create a policy

Add rules

Authentication

MCP server

Documentation

JSON mode

Configuration files

Local webhook testing

Continue a generated payment example