CLI Quickstart

# CLI Quickstart

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

- Human URL: https://conto.finance/docs/cli/quickstart
- Raw Markdown: https://conto.finance/docs/cli/quickstart.md
- Terminal view: https://conto.finance/ai/docs/cli/quickstart

Documentation group: Build

## Install & Run

Run with `npx`:

```bash
npx @conto_finance/create-conto-agent
```

Or install globally:

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

The wizard provisions everything your agent needs: a wallet, a spending policy, and an SDK key. No
manual dashboard steps are 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
# 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 `.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

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

    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 and its expiration time back to the CLI
    automatically. Browser-issued organization credentials expire after seven days; run
    `conto login` again to renew one.

    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.

    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.

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

  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

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

### Commands Reference
Link: https://conto.finance/cli/commands

    Full list of CLI commands and flags

### Policy Management
Link: https://conto.finance/cli/policies

    Create and manage spending policies from the CLI