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.
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 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:
codeis the server’s code, a call’serror_code, or a CLI code such asusage,missing_keyorinvalid_jq.fixappears on errors the CLI raises itself, such asmissing_key, and says what to change.status,retry_afterandrequest_idappear when the response had an HTTP status, aRetry-Afterheader and anx-request-idheader.dataholds the full response body of a failed request. Errors from--jsonfields and--jqcarry nodataand never print the response.
Output
--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.
--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 forRetry-Afterwhen the server sends it, otherwise 0.5 then 1 second. - A
Retry-Afterlonger than 60 seconds is not waited out: the command exits 6 at once withretry_afterset. - Writes retry only on the routes that enforce
Idempotency-Key, and only when signed in: create, revise and rebuild an API, and:calland:batchon 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 --timeoutalso bounds these waits. When a wait would pass it, the command exits 9.- An error with
retryset tofix_requestis 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 isdefault.
--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:
Add Peel to a coding agent
init adds the Peel MCP server to Claude Code, Codex or Cursor.
- 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
peelentry is reported as already configured and left alone.--forcereplaces 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 whosepeelentry it could not change is reported asconfig_update_failed, and nothing is written. - Each entry reads
PEEL_API_KEYwhen the client starts; set it from the stored profile withexport PEEL_API_KEY="$(bun --no-env-file --config=bunfig.toml cli/src/cli.ts auth token)". - Only the
peelentry changes. Other servers in the file are kept, and a file it cannot parse is left alone with an error. - Without
--targetit detects which clients are installed. Without--yesit prints the change as a diff and asks; with--no-input,--cior--jsonit 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.
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 for them.