@conto_finance/create-conto-agent. It provides the
create-conto-agent and conto commands. Run it with npx to start the setup wizard:
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.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.localconto.config.json: agent metadataexample.mjs: runnable payment example
.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.
Run the example
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:.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
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.
--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
--json for the full record, including source wallet, authorization decision, and block details.
Wallets
Spending limits
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".
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.
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.
All policy commands support --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.
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 CLI0.7.0 or later.
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
CONTO_WEBHOOK_SECRET when it is set, without printing it. Add Slack, Telegram, and WhatsApp channels in
Settings > Notifications.
Owner review
The key thatconto 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:
- The CLI prints a review link and opens it in your browser.
- An owner or admin signs in and confirms or declines the change.
- The CLI waits and reports the outcome. A new SDK key is shown once, in the terminal that asked.
--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.
Authentication
~/.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
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 byexample.mjs. After owner review or an interrupted run,
check or resume that same request instead of starting another payment:
Save a controlled-payment test report
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.