Skip to main content
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. 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:
  • 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

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

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 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.
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 for them.