# Conto CLI Set up an AI agent with Conto spending controls. Conto is a buyer-side control layer. Integrate it in the agent owner's runtime or payment tools. The owner or budget holder sets policy before the agent pays. See [buyer-side control](https://conto.finance/docs/introduction/concepts) for the authorization and execution boundary. Node.js 20.19+. Create a temporary simulated sandbox without an account: ```bash mkdir conto-first-payment cd conto-first-payment npx @conto_finance/create-conto-agent --sandbox --json node example.mjs --execute npx @conto_finance/create-conto-agent doctor ``` Success is `Status: completed` and `Settlement mode: test`. The CLI stores credentials in `.env.local`, adds that file to `.gitignore`, and installs the `conto` command locally. The sandbox setup key, which configures the sandbox's policies and spend limits, goes to `.conto/sandbox-setup.env` instead, so the agent runtime that loads `.env.local` never holds it. See [configure controls](https://conto.finance/docs/quickstart/agent-sandbox#configure-controls). Run the wizard without `--sandbox` to sign in and provision a managed wallet. Choose Tempo Testnet for free faucet tokens and actual onchain test transfers. For headless organization setup, set `CONTO_ORG_API_KEY` or pass `--api-key`. A mainnet setup asks you to confirm the network (pass `--confirm-mainnet` when headless) and creates the agent in the `PROD` environment, because only `PROD` agents can pay from mainnet wallets. Testnet setups create a `DEV` agent. Inside a CLI-created project, `npx conto ` is a shorter form of the same commands. Outside one, bare `npx conto` fetches an unrelated npm package, so use the full package name. `--help`, `--version`, and `--json` work without an interactive terminal. Test a local webhook handler with the same development secret configured in that handler: ```bash export CONTO_WEBHOOK_SECRET="your-local-development-secret" npx @conto_finance/create-conto-agent webhooks test http://localhost:8080/webhooks/conto --json ``` This sends one synthetic signed event to a loopback address. It creates no payment and requires no API key. `npx @conto_finance/create-conto-agent pay
--dry-run` validates the payment locally and prints the request it would send. It contacts nothing and does not evaluate policy. Use `npx @conto_finance/create-conto-agent limits` to see current limits. ## Hand a sandbox to its owner ```bash npx @conto_finance/create-conto-agent sandbox claim --json npx @conto_finance/create-conto-agent sandbox claim --wait --timeout 300 --json npx @conto_finance/create-conto-agent sandbox claim-status --json ``` `sandbox claim` uses the sandbox organization key, `CONTO_SANDBOX_API_KEY` from the environment or `.env.local`, and no other key. It returns a `verificationUrl`, its `expiresAt`, and the `requestedPermission`. Send the URL only to the person who will own the sandbox. It holds a temporary secret. The polling token stays in `.conto/sandbox-claim.json`, which is owner-only and git-ignored, and is never printed. Running `sandbox claim` again reuses a pending link. `--wait` checks the claim at the interval the server returns, backs off when rate limited, and stops at `--timeout` (default 300 seconds). A timeout or Ctrl+C keeps the link, so the next run continues with it. With `--json`, a newly issued link is returned right away so it can be delivered, and the next `--wait` waits on it. `claim-status` reports `pending`, `claimed`, or `expired` without printing the link. Claiming 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. | 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 | ## Finish an interrupted setup 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. ```bash npx @conto_finance/create-conto-agent --resume --api-key --json ``` Resume checks each recorded resource and creates only what is missing. It refuses a different base URL, organization, or configuration. When the answer to a create request was lost, setup stops with `"status": "reconciliation_required"` and the resume looks the resource up before creating anything. An SDK key whose secret never reached this machine cannot be recovered. An owner revokes it, and the resume issues a new one. `--restart` discards the record and starts a new setup. 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 | ## Documentation - [CLI quickstart](https://conto.finance/docs/cli/quickstart) - [First payment](https://conto.finance/docs/quickstart/setup) - [Commands](https://conto.finance/docs/cli/commands) - [Recovery](https://conto.finance/docs/guides/payment-lifecycle) - [Developer support](mailto:support@conto.finance)