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

> ## Agent Instructions
> Peel builds APIs from a URL and a task. Use only the REST routes under https://api.peel.sh and the hosted MCP server at https://api.peel.sh/mcp. Authenticate with the X-API-Key header, or send the same key as Authorization: Bearer. Errors carry code, message, retryable, retry, docs_url and details; branch on code. The peel CLI and the open-source SDK are not published; do not run npm install peel, which is an unrelated package. The keyless routes need no key and no session: the GET /public/marketplace routes, POST /v1/marketplace/{marketplace_id}/endpoints/{endpoint_name}:call and https://api.peel.sh/mcp/keyless. Account routes take a key or a signed-in session and answer 401 without one. These take only a session from peel.sh and refuse a key: GET /v1/accounts, POST /v1/accounts/join, POST /v1/accounts/{account_id}/leave, POST /v1/team/invites, GET /v1/connected-apps, DELETE /v1/connected-apps/{client_id}, PUT /v1/logins, DELETE /v1/logins, GET /v1/logins/code and the /account/billing routes. Every route with its schemas is in https://docs.peel.sh/openapi.json. Use the exact route, field and error-code names shown in these pages, and read the API Reference tab for request and response schemas.

# CLI reference

> Exit codes, the JSON error shape, output flags, retries, profiles, MCP setup and shell completion for the command-line tool, which runs from a checkout until it is published.

The command-line tool is not published yet. It runs from a checkout of the Peel repository, so the examples below start with `bun --no-env-file --config=bunfig.toml cli/src/cli.ts` from the checkout root. `--no-env-file` stops Bun from loading a `.env` from the current folder, and `--config=bunfig.toml` names the checkout's Bun config so no other folder's `bunfig.toml` can preload code. Keep both flags if you wrap the command in a shell function that runs from other folders. Every command's `--help` lists its flags and the REST route it calls.

## Exit codes

Scripts and agents can branch on the exit code without reading the message.

| Code | Meaning |
| - | - |
| 0 | Success. |
| 1 | Any other failure. |
| 2 | Usage error: an unknown flag or command, a missing argument, a word the command does not take (such as `idd` in `keys create --json idd`, named in the message; a word that looks like a key or token is called "a word that looks like a key" and never printed), a bad `--jq` expression or `--json` field, or a prompt that `--no-input` refused. |
| 3 | Not signed in, an invalid or expired key, or a browser sign-in that expired, was refused or could not open. |
| 4 | The key or the role is not allowed to do this, including a key limited to another API. |
| 5 | The API, endpoint, run or file was not found. |
| 6 | Rate limited, out of quota or past a plan limit, or the server asked to wait more than 60 seconds. |
| 7 | Server or network failure after the retries below. |
| 8 | The API rejected the input. |
| 9 | Timed out waiting, for example for a build. |

The code comes from the error's `code` field and, when that code is not in the table, from the HTTP status: 400 and 422 give 8, 401 gives 3, 403 gives 4, 404 gives 5, 408 gives 9, 429 gives 6 and 5xx gives 7. It never comes from the message text. The [error codes](https://docs.peel.sh/reference/errors.md) page lists the server's codes.

## JSON errors

With `--json`, `--jq`, or whenever output is not a terminal, a failure prints one JSON object on stdout, then exits with the code above:

```json theme={null}
{
  "code": "rate_limited",
  "message": "Too many requests",
  "status": 429,
  "retry_after": 120,
  "request_id": "req_123",
  "data": { "code": "rate_limited", "message": "Too many requests", "retryable": true, "retry": "same_key" }
}
```

* `code` is the server's code, a call's `error_code`, or a CLI code such as `usage`, `missing_key` or `invalid_jq`.
* `fix` appears on errors the CLI raises itself, such as `missing_key`, and says what to change.
* `status`, `retry_after` and `request_id` appear when the response had an HTTP status, a `Retry-After` header and an `x-request-id` header.
* `data` holds the full response body of a failed request. Errors from `--json` fields and `--jq` carry no `data` and never print the response.

In a terminal the same error prints as one line on stderr, followed by the fix.

## Output

| Flag | Effect |
| - | - |
| `--json` | Print the response as JSON. In a terminal, the available fields are listed on stderr. |
| `--json=id,name` | Keep only these fields on each record, like `gh`. An unknown field exits 2 and lists the names of the fields that exist. |
| `--jq <expr>` | Filter the JSON with a jq expression. Strings print without quotes. |
| `--output <field>` | On `build`, `call` and `apis get`, print one field as plain text for shell pipelines. |
| `--no-color` | Plain output. `NO_COLOR` does the same. |
| `--no-input` | Never prompt. A command that needs an answer exits 2 instead. |
| `--ci` | Non-interactive mode for scripts. |

`--json` alone is a switch and never takes the next word, so `call --json <api-id> <endpoint>` works; `--no-json` turns it off. Fields are picked only with `--json=`. A field list applies to the records of a list response, such as the `apis` array of a list, and to the object otherwise. `--jq` runs on that result, so without a field list it sees the whole response.

```bash theme={null}
bun --no-env-file --config=bunfig.toml cli/src/cli.ts apis list --json=id,status
bun --no-env-file --config=bunfig.toml cli/src/cli.ts apis list --jq '.apis[] | select(.status == "completed") | .id'
```

`--jq` is a subset of jq built into the CLI. It supports paths (`.a`, `.[0]`, `.[]`, `.[1:3]`, `..`, `?`), pipes, commas, `//`, `and`, `or`, `not`, comparisons, arithmetic, array and object construction, and these functions: `length`, `keys`, `values`, `first`, `last`, `add`, `sort`, `sort_by`, `unique`, `reverse`, `min`, `max`, `flatten`, `to_entries`, `from_entries`, `select`, `map`, `has`, `join`, `split`, `startswith`, `endswith`, `test`, `contains`, `tostring`, `tonumber`, `type`, `any`, `all`, `ascii_downcase`, `ascii_upcase` and `empty`. An unknown function or a syntax error exits 2 before any request is sent.

## Retries

* Reads (`GET`, `HEAD`) retry on 429, 502, 503, 504 and network errors, at most 3 attempts. The CLI waits for `Retry-After` when the server sends it, otherwise 0.5 then 1 second.
* A `Retry-After` longer than 60 seconds is not waited out: the command exits 6 at once with `retry_after` set.
* Writes retry only on the routes that enforce `Idempotency-Key`, and only when signed in: create, revise and rebuild an API, and `:call` and `:batch` on your APIs and on the marketplace. The CLI sends one key per command, so every retry carries the same key.
* Every other write, including any signed-out marketplace call, is sent once, whatever the error. A redirect in answer to a write is an error, and the write is not sent again.
* A read follows redirects on the same origin, up to 20 hops. A redirect to another origin exits 1 with `cross_origin_redirect`, naming both origins, and the key is never sent there.
* `build --timeout` also bounds these waits. When a wait would pass it, the command exits 9.
* An error with `retry` set to `fix_request` is never retried.

## Profiles

A profile is a named key and base URL in the credentials file, which is written with mode 0600. Without a name the profile is `default`.

```bash theme={null}
bun --no-env-file --config=bunfig.toml cli/src/cli.ts auth login --profile staging --base-url https://staging.example.test
PEEL_PROFILE=staging bun --no-env-file --config=bunfig.toml cli/src/cli.ts apis list
bun --no-env-file --config=bunfig.toml cli/src/cli.ts auth token --profile staging
```

The key comes from `--api-key`, then `PEEL_API_KEY`, then the profile. When `--profile` or `PEEL_PROFILE` names a profile, `PEEL_API_KEY` and `PEEL_API_BASE_URL` are ignored, so a staging profile never picks up a production key from the environment. `auth logout` clears only the named profile. `auth token` prints the key the CLI would use. A base URL from `--base-url`, `PEEL_API_BASE_URL` or a profile must be an http or https URL with no user name or password; any other exits 2 without echoing it.

## Browser sign-in

`auth login` without a key opens the browser and waits for approval, for at most 15 minutes or until the code expires. It exits 3 with:

| Code | When |
| - | - |
| `device_code_expired` | The code expired before it was approved. |
| `device_login_refused` | The server refused the sign-in. |
| `no_browser` | No browser opened and nobody is at the terminal, such as in a sandbox. Pass `--browser` to wait anyway and open the link on another device, or pass `--api-key`. |

## Add Peel to a coding agent

`init` adds the [Peel MCP server](https://docs.peel.sh/features/mcp-server.md) to Claude Code, Codex or Cursor.

```bash theme={null}
bun --no-env-file --config=bunfig.toml cli/src/cli.ts init
bun --no-env-file --config=bunfig.toml cli/src/cli.ts init --target claude-code,codex --yes
bun --no-env-file --config=bunfig.toml cli/src/cli.ts init --remove --target cursor --yes
```

| Client | File | Entry |
| - | - | - |
| Claude Code | `.mcp.json` in the current folder | `X-API-Key: ${PEEL_API_KEY}` |
| Cursor | `.cursor/mcp.json` in the current folder | `X-API-Key: ${env:PEEL_API_KEY}` |
| Codex | `config.toml` in `CODEX_HOME`, default `~/.codex` | `bearer_token_env_var = "PEEL_API_KEY"` |

* It never writes or prints a key. A key already in a file prints masked, as at most its first 6 and last 4 characters.
* An existing `peel` entry is reported as already configured and left alone. `--force` replaces it.
* It refuses to write through a symbolic link, and writes each file through a new temporary file in the same folder, which replaces the file only once every byte is written.
* A file it cannot parse, or whose top level is not an object, is left alone and reported by path as `config_unparseable`, with the line when it is known, never with the file's text. A file it parsed but whose `peel` entry it could not change is reported as `config_update_failed`, and nothing is written.
* Each entry reads `PEEL_API_KEY` when the client starts; set it from the stored profile with `export PEEL_API_KEY="$(bun --no-env-file --config=bunfig.toml cli/src/cli.ts auth token)"`.
* Only the `peel` entry changes. Other servers in the file are kept, and a file it cannot parse is left alone with an error.
* Without `--target` it detects which clients are installed. Without `--yes` it prints the change as a diff and asks; with `--no-input`, `--ci` or `--json` it exits 2 with the planned change instead of asking.

## Shell completion

`completion` prints a script generated from the command tree, with every command, subcommand and flag.

```bash theme={null}
source <(bun --no-env-file --config=bunfig.toml cli/src/cli.ts completion bash)
source <(bun --no-env-file --config=bunfig.toml cli/src/cli.ts completion zsh)
bun --no-env-file --config=bunfig.toml cli/src/cli.ts completion fish > ~/.config/fish/completions/peel.fish
```

The scripts complete a command named `peel`, so define `peel` as a shell function or alias for the entry file first.

## Commands that need a session

Inviting a teammate and switching or leaving accounts need a signed-in peel.sh session, which an API key cannot give. `team invite` and `accounts` print the link to the team settings page and exit 2. Use [peel.sh/settings](https://peel.sh/settings?tab=team) for them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.