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

# CLI

> Use Peel from the terminal for setup, auth, builds, calls, exports, and MCP wiring.

The Peel CLI is the fastest way to use the hosted product from a terminal or coding agent.

It covers the common public-endpoint lifecycle:

* authenticate
* build an API from a URL
* inspect its published contract
* call endpoints
* revise or rebuild later
* export OpenAPI or MCP
* install the hosted MCP server into local agent clients

For target-site `session_required` endpoint calls, run the API's login endpoint first, then pass the returned `session_id` and `encryption_key` with `peel call --session-id ... --encryption-key ...`.

## Install status

<Info>
  The public npm release is not live yet. The package name is `@peel/cli`, but for now the supported install path is a source checkout.
</Info>

## Run it today from source

```bash theme={null}
git clone https://github.com/peel-sh/peel.git
cd peel
bun install
alias peel='bun run cli --'
peel --help
```

The CLI defaults to the hosted Peel API at `https://api.peel.sh`. Browser auth and `peel open` still take you to the Peel app at `https://peel.sh`. Override the API host with `PEEL_API_BASE_URL`, legacy `PEEL_BASE_URL`, or `--base-url` when you want to point at another deployment.

```bash theme={null}
export PEEL_API_BASE_URL=https://api.peel.sh
```

## First-time setup

`peel setup` is the canonical onboarding path.

```bash theme={null}
peel setup
```

It does three things in one pass:

1. authenticates you
2. installs MCP config for detected agent clients
3. runs `peel doctor`

Supported MCP targets today:

* `claude-code`
* `codex`
* `cursor`
* `claude-desktop`
* `all`

Useful setup flags:

```bash theme={null}
peel setup --api-key sk_... --target all --ci
peel setup --skip-mcp --skip-doctor
peel setup --install-skill --skill-target codex
```

Use `--ci` or `--json` for fully non-interactive setup. Passing `--api-key` and `--target` skips auth and MCP target prompts, but interactive setup may still offer coding-agent skill installation unless you opt into CI or JSON mode.

## Auth flows

### Browser device flow

`peel auth login` uses device-code browser auth by default.

```bash theme={null}
peel auth login
```

The CLI prints a short code, opens a browser, and stores the resulting API key locally after you approve the login.

The approval session is held server-side until exchange completes, so the flow survives the normal handoff between the CLI poller and the signed-in browser.
The public OpenAPI spec documents the CLI-facing `POST /public/device/start` and `POST /public/device/exchange` helpers; the browser approval step stays inside the signed-in Peel app.

### Direct API key

For CI or headless environments, pass a key directly:

```bash theme={null}
peel auth login --api-key sk_...
```

Or export it first:

```bash theme={null}
export PEEL_API_KEY=sk_...
```

### Signup, status, and logout

```bash theme={null}
peel auth signup --email you@example.com --password 'secret123'
peel auth status
peel auth logout
```

`signup` is only available when the target server has public signup enabled. On `peel.sh`, signup is closed during private preview. Use `peel auth login` with an existing account or `peel auth login --api-key ...` with a key from settings.

## Build, inspect, and call

```bash theme={null}
peel build https://news.ycombinator.com --instructions "Get top stories with title, score, and author"
peel apis list
peel apis get <api-id>
peel call <api-id> <endpoint_name> -p limit=10
```

Key behaviors from the current CLI:

* `peel build` waits for completion by default
* `matched: true` means Peel reused an existing compatible API
* `peel apis get` is the main contract-inspection command before runtime calls
* `peel apis get` shows endpoint `runtime_policy` and `runtime_verification` metadata when Peel has deterministic runtime constraints or build-time verification evidence for an endpoint
* `peel call` accepts repeatable `-p key=value`, full JSON with `--params`, or request JSON from `--stdin`
* On successful HTTP responses, `peel call` prints the same sanitized response envelope as REST `:call`: `status`, `status_code`, `data`, `error`, `error_code`, `execution_time`, and optional `transport`, `session_id`, `encryption_key`, and `raw_output`
* On non-2xx responses, `peel call` exits with a CLI error wrapper. Use `--json` when scripts need the runtime envelope under the wrapper's `data` field.
* `peel call --session-id ... --encryption-key ...` sends target-site session credentials for `session_required` endpoints

Examples:

```bash theme={null}
peel build https://docs.astral.sh/uv/ --instructions "List CLI commands and flags"
peel apis get <api-id>
peel call <api-id> list_commands --params '{"section":"reference"}'
peel call <api-id> inbox --params '{"limit":10}' --session-id "$SESSION_ID" --encryption-key "$ENCRYPTION_KEY"
echo '{"query":"pricing"}' | peel call <api-id> search_docs --stdin
```

## Check balance and health

```bash theme={null}
peel credits
peel apis health <api-id>
```

Use `peel credits` before long build batches or expensive runtime calls. Use `peel apis health` before deciding whether to revise or rebuild, and to distinguish `pending_build` from `build_failed` when an API has not published a binding yet. For failed builds, `peel apis health` prints the same structured `failure` diagnostics as `peel apis get`.

## Revise, rebuild, and respond

```bash theme={null}
peel revise <api-id> --instructions "Add author bios and article dates"
peel rebuild <api-id>
peel respond <api-id> --body '{"search_term":"headphones"}'
```

Use them the same way you would use the corresponding REST routes:

* `revise` when the site is right but the requested shape is wrong
* `rebuild` when the site changed or the compiled evidence drifted
* `respond` when `peel apis get` shows `status: needs_input`

Both `revise` and `rebuild` support `--yes` and `--dry-run`.

## Export and MCP

```bash theme={null}
peel apis export <api-id> --format openapi > peel-api.openapi.json
peel apis export <api-id> --format mcp > peel-api.mcp.json
peel mcp add --target codex
peel mcp remove --target codex
```

Use export when you need a file artifact. Use `peel setup` or `peel mcp add` when you want your local agent client to talk to the hosted MCP server directly.

## Open the hosted app

```bash theme={null}
peel open
peel open <api-id>
```

`peel open` launches the hosted app in a browser. Passing an `api-id` opens that API directly.

## Machine-readable mode

Most commands support `--json`. Use it for CI, agent wrappers, and shell pipelines.

```bash theme={null}
peel build https://example.com --instructions "Extract products" --json
peel credits --json
peel apis get <api-id> --json
```

## Related pages

* [Quickstart](/getting-started/quickstart)
* [Authentication](/getting-started/authentication)
* [MCP server](/features/mcp-server)
* [API updates](/features/api-updates)
* [Exporting an API](/reference/exports)