Introspection CLI

The CLI signs in as you through a browser approval flow. It is the operator surface for a project, where you author and administer the objects your agents run against: create the first runtime, define a recipe or an experiment, choose what staging serves, disable a bad version, and configure secrets. Production normally follows the repository’s default branch. See SDKs when you need the application-facing libraries instead.

The CLI reference spans four pages:

• This page — install, toolchain setup, login, upgrade, diagnosis, and the global output contract.
• Local recipe commands — init, check, local, dev, skills, and the dashboard shortcut.
• Project administration — API keys, applications, bindings, repositories, connectors, runtimes, and recipe records.
• Production signals & evals — tasks, files, shares, production evidence, offline evals, judges, telemetry, and experiments.

For step-by-step instructions, use the Guides to build, deploy, and improve an agent. Come back here when you need a command or flag.

Install

Install Node.js 24 or later , then choose one package manager:

pnpm add --global @introspection-ai/cli

bun add --global @introspection-ai/cli

yarn global add @introspection-ai/cli

npm install --global @introspection-ai/cli

If pnpm reports that it has no global binary directory, run pnpm setup once and restart the shell before installing the CLI. That command configures pnpm’s own global directory and PATH; Introspection does not edit your shell profile.

Set up the local toolchain

There are two equally supported ways to work with the CLI. In the agent-led flow — the Quickstart path where a coding agent such as Codex or Claude Code drives the CLI for you — the coding agent runs setup when its selected workflow first needs Pi and Recipes; the user does not run it manually. If you are operating directly from a terminal instead, run the interactive setup yourself:

introspection setup

Setup converges the machine on one supported state:

• installs Pi with its official npm method when Pi is absent;
• asks an existing Pi below the Recipes minimum to update itself, while accepting newer Pi versions;
• installs or repairs the exact compatible Recipes extension.

Pi remains independent and user-owned: setup never downgrades a newer Pi or replaces a working installation, and when NVM already provides a compatible Node.js version it uses that without changing your shell’s default.

For automation, --check prints the plan without changing anything and --yes authorizes the complete plan, including Pi changes.

--target harbor prepares only the optional Harbor toolchain (uv, Harbor, and the Introspection Recipe agent) instead of the Pi/Recipes plan. Run it once before the first introspection eval run -p <harbor-path>; --check prints the Harbor plan without installing anything:

introspection setup --target harbor --check
introspection setup --target harbor

Log in

introspection login
introspection whoami

Login uses the OAuth 2.0 Device Authorization flow; select the project on the browser approval page, and the server resolves the agent identity your development session acts as for you. The CLI stores the identity- and project-bound session at ~/.introspection/credentials.json with mode 0600 and refreshes it transparently. whoami validates the session and prints the Control Plane/Data Plane targets, granted scope, organization, project, member, token and session status, and expiry, without printing tokens. Run login again to switch project or development identity; project-scoped commands also accept --project.

The server always chooses the CLI capabilities: runtimes for platform operations and remotes for introspection dev. There is no capability flag. Project API keys and applications cannot request the CLI-only remotes scope.

introspection logout

Command map

Run introspection <group> --help for the version-installed flag contract. A bare introspection with no arguments prints a status view of where you are, not the command index; use introspection --help for the index.

Diagnose the local toolchain

introspection doctor is the read-only diagnosis of the CLI, Recipes, Pi, Node, and local recipe readiness. It changes nothing.

introspection doctor

The two checks answer different questions: setup --check renders the plan to reach a ready machine, doctor reports the state of the machine you are on.

Upgrade

introspection upgrade
introspection upgrade --dry-run
introspection upgrade --format json
introspection upgrade --dismiss

--format json emits the upgrade plan as JSON and implies --dry-run, so it never changes anything. --dismiss silences the ambient notice until a release newer than the current latest ships.

The CLI checks the npm latest tag in the background, throttled to roughly once every 20 hours. Notices go to stderr and never corrupt structured output.

Structured output

Data commands accept global output and projection flags:

introspection runtimes list -o table
introspection recipes list --query "[].id"
introspection bindings endpoints list \
  --query "[?kind=='mcp'].{id:id,name:name,url:base_url}" \
  -o table

• -o / --output: json (default), jsonc, table, or report. report renders the diagnosis that doctor and check produce; a command with no report of its own falls back to table.
• --query: a JMESPath  expression applied before formatting.
• --yes / -y answers every confirmation prompt, and --non-interactive makes a command fail with the missing flag rather than wait for a terminal.

Structured results go to stdout; progress and confirmations go to stderr, so JSON remains safe to pipe.

Success is exit 0; usage errors — an unknown command, a missing or malformed flag — exit 2, CLI pre-request read validation is exit 3, and runtime/API failures are exit 1. List commands return an array for the fetched page only: follow next/--next, or use --page-all where supported, rather than inferring exhaustiveness from one page. Task streams are replayable only within a bounded window, so treat resume_gap as incomplete history and refetch durable task or conversation state.

Related

• Authentication: CLI login versus SDK API keys.