> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Quickstart

> Set up an agent with wallet, policies, and SDK key in one command

## Install & Run

Run with `npx`:

```bash theme={null}
npx @conto_finance/create-conto-agent
```

Or install globally:

```bash theme={null}
npm install -g @conto_finance/create-conto-agent
create-conto-agent
```

The wizard provisions everything your agent needs: a wallet (custody chosen by the server, Privy on the hosted instance), a spending policy, and an SDK key. No manual dashboard steps required.

The package exposes both the `create-conto-agent` and `conto` bins. The wizard installs itself
into your project as a dev dependency, so `npx conto <command>` resolves to the real Conto CLI
from inside the project directory. Outside a project with that dependency, use the full package
name (`npx @conto_finance/create-conto-agent <command>`) or a global install; a bare `npx conto`
would fetch an unrelated npm package that happens to own that name.

## Headless And Agent Runs

The wizard needs an interactive terminal and a browser. For CI, scripts, and autonomous agents,
use one of the noninteractive modes instead:

```bash theme={null}
# Anonymous test-mode sandbox: no account, no browser, no prompts.
# Expires after 7 days. Payments execute in simulated mode.
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 `.env.local`, `.gitignore`, `conto.config.json`, and `example.mjs` files
as the wizard. The credential files are created with owner-only permissions, and `.env.local` is
added to `.gitignore`. `--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.

Sandbox mode also writes `CONTO_SANDBOX_API_KEY`, `CONTO_SANDBOX_EXPIRES_AT`, and
`CONTO_SANDBOX_EXECUTION=simulated`, so follow-up commands like `npx conto doctor` can report
simulated execution correctly instead of treating the sandbox wallet as a broken manual flow.

## What Happens

<Steps>
  <Step title="Configure your agent">
    Choose your agent name, type, daily spending limit, and network.
  </Step>

  <Step title="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 redirects the token back to the CLI automatically.
  </Step>

  <Step title="Resources are provisioned">
    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.
  </Step>

  <Step title="Files are written">
    Four files are written or updated 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

    The wizard also adds `@conto_finance/create-conto-agent` as a dev dependency (creating a
    minimal `package.json` if the directory has none) so `npx conto <command>` works. Pass
    `--no-install` to skip this.
  </Step>
</Steps>

## Supported Networks

| Network           | Currency | Chain ID       | Notes                                          |
| ----------------- | -------- | -------------- | ---------------------------------------------- |
| **Tempo Testnet** | pathUSD  | 42431          | Evaluation default; auto-funded via faucet     |
| Tempo             | USDC.e   | 4217           | Mainnet; real settlement requires confirmation |
| Base              | USDC     | 8453           | Mainnet; real settlement requires confirmation |
| Solana            | USDC     | solana-mainnet | Mainnet; real settlement requires confirmation |

The wizard lists every chain returned by `/api/chains` (including Ethereum, Arbitrum, Polygon,
Base Sepolia, and Solana Devnet); the table above covers the most common choices. The first run
defaults to Tempo Testnet so evaluation cannot move real funds. Tempo Mainnet uses `USDC.e`;
Tempo Testnet uses `pathUSD`.

<Info>
  On Tempo Testnet, the wizard automatically funds your wallet via faucet, no manual funding
  needed.
</Info>

<Warning>
  Choosing any mainnet prompts for confirmation. Headless setup must include `--confirm-mainnet`
  together with an explicit mainnet `--chain`, for example `--chain 4217 --confirm-mainnet`.
</Warning>

## Run the Example

```bash theme={null}
node example.mjs            # Check setup + request a test payment (no funds move)
node example.mjs --execute  # Also execute the payment if policies approve it
```

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.

## Next Steps

After setup, use the `conto` CLI for day-to-day operations (from the project directory):

```bash theme={null}
npx conto doctor          # Verify auth, scopes, wallet, chain, balance, base URL
npx conto status          # Agent info and spending summary
npx conto pay --dry-run 0x... 10   # Test a payment against policies
npx conto pay 0x... 10    # Request + execute a payment
npx conto mcp             # Start the MCP server for Claude
```

<CardGroup cols={2}>
  <Card title="Commands Reference" icon="terminal" href="/cli/commands">
    Full list of CLI commands and flags
  </Card>

  <Card title="Policy Management" icon="shield" href="/cli/policies">
    Create and manage spending policies from the CLI
  </Card>
</CardGroup>