# CLI

Install the `introspection` CLI, prepare your machine, sign in, and find the command you need.

The `introspection` CLI builds, ships, and operates your agents. Run
`introspection <command> --help` for the exact flags of your installed version.

## Install

Install [Node.js 24 or later](https://nodejs.org/), then:

```bash
npm install --global @introspection-ai/cli
```

`pnpm add --global`, `bun add --global`, and `yarn global add` work too (with
pnpm, run `pnpm setup` once if it has no global bin directory).

## Set up your machine

```bash
introspection setup          # Pi, Recipes, and a discovery skill for coding agents
```

`--check` prints the plan without changing anything; `--yes` approves it
without prompting (for CI). Safe to re-run. For coding agents, see
[Using a coding agent](/reference/agents).

## Log in

```bash
introspection login
introspection whoami
```

Approve the device login in the browser and pick the project there. The
session (and the project's URLs) is stored in `~/.introspection/credentials.json`
and refreshed for you; `logout` deletes it. `whoami` shows the project,
member, and scopes. A login covers one project: log in again to switch
([project rules](/reference/cli/admin#projects)), and you then see only that
project's runtimes and conversations.

| Flag | Effect |
| --- | --- |
| `--url` / `INTROSPECTION_API_BASE_URL` | Another deployment's API URL (the SDKs read `INTROSPECTION_BASE_API_URL`). |
| `--capabilities <list>` | Narrow the login's data-plane and Git token to some of `runtimes`, `reviews`, `evals`, `git`; it can only take away. |

Management commands act with your member role. Integrations, plan, and
billing are dashboard-only, and a login cannot run `automations`
([why](/reference/cli/admin#automations)).

## Use an API key

Some commands accept a project API key through `--token` or
`INTROSPECTION_TOKEN`, so they run in CI without a login
([Credentials](/identity/credentials)):

| Accepts an API key | Always acts as your login |
| --- | --- |
| `tasks`, `conversations`, `events`, `metrics`, `files`, `shares`, `tags`, `images`, `annotations list`, `repositories contents`/`commits`/`commit` (these also need a login) | `runtimes`, `recipes`, `repositories list`/`add`/`remove`, `bindings`, `connectors`, `applications`, `api-keys`, `members`, `experiments`, `judges list`/`get`/`update` |

An environment-scoped key only selects the environment. With a production
key, `tasks create`, `tasks delete`, `files upload` and `shares create` still
change production (`files delete` also needs the `evals` capability).

## Diagnose and upgrade

| Command | Does |
| --- | --- |
| `doctor [-o report]` | Reports CLI, Recipes, Pi, Node, and local recipe readiness; changes nothing. |
| `upgrade [--dry-run] [--format json] [--dismiss]` | Updates the CLI, Recipes, and Pi; `--dismiss` silences the notice until the next release. |

## Output flags

These flags work on every command:

| Flag | Effect |
| --- | --- |
| `-o`, `--output` | `json` (default), `jsonc`, `table`, or `report`. `report` renders a report from `doctor`, `check`, and `eval` (the default for `eval` in a terminal); other commands fall back to `table`. |
| `--query` | A [JMESPath](https://jmespath.org) expression applied before formatting. |
| `-y`, `--yes` | Answer every confirmation prompt with yes. |
| `--non-interactive` | Fail with the missing flag instead of waiting for terminal input. |

```bash
introspection runtimes list -o table
introspection bindings endpoints list \
  --query "[?kind=='mcp'].{id:id,name:name,url:base_url}" -o table
introspection metrics query @q.json --query "data[0].metrics[0].value" -o table
```

`-o table` prints a single value bare, so `--query id -o table` gives a raw id.

Results go to stdout, progress to stderr. Exit codes: `0` success, `1` any
failure (including API errors), `2` usage error, `3` a telemetry read rejected
before the request. List commands return one page; follow `--next`, or use
`--page-all` where a list offers it.

## Command map

| Step | Commands | Reference |
| --- | --- | --- |
| Set up | `setup`, `skills`, `doctor`, `upgrade`, `login`, `logout`, `whoami` | This page |
| Build | `init`, `check`, `local`, `dev`, `open`, `recipes` | [Develop locally](/build/local) |
| Ship | `runtimes`, `bindings` | [Deploy & operate](/reference/cli/deploy) |
| Run | `tasks` | [Deploy & operate](/reference/cli/deploy#tasks) |
| Debug | `conversations`, `events`, `metrics`, `annotations` | [Evals & telemetry](/reference/cli/evals) |
| Evaluate | `eval`, `judges`, `images` | [Evals & telemetry](/reference/cli/evals) |
| Experiment | `experiments` | [Evals & telemetry](/reference/cli/evals#experiments) |
| Administer | `api-keys`, `applications`, `members`, `repositories`, `connectors`, `files`, `shares`, `tags`, `automations` | [Admin](/reference/cli/admin) |

## Next

- [Deploy & operate](/reference/cli/deploy): runtimes, bindings, tasks.
- [Evals & telemetry](/reference/cli/evals): conversations, evals, judges, experiments.
- [Admin](/reference/cli/admin): keys, applications, members, connectors, files.

CLI

Install the introspection CLI, prepare your machine, sign in, and find the command you need.

The introspection CLI builds, ships, and operates your agents. Run introspection <command> --help for the exact flags of your installed version.

Install

Install Node.js 24 or later , then:


npm install --global @introspection-ai/cli

pnpm add --global, bun add --global, and yarn global add work too (with pnpm, run pnpm setup once if it has no global bin directory).

Set up your machine


introspection setup          # Pi, Recipes, and a discovery skill for coding agents

--check prints the plan without changing anything; --yes approves it without prompting (for CI). Safe to re-run. For coding agents, see Using a coding agent.

Log in


introspection login
introspection whoami

Approve the device login in the browser and pick the project there. The session (and the project’s URLs) is stored in ~/.introspection/credentials.json and refreshed for you; logout deletes it. whoami shows the project, member, and scopes. A login covers one project: log in again to switch (project rules), and you then see only that project’s runtimes and conversations.

Flag	Effect
`--url` / `INTROSPECTION_API_BASE_URL`	Another deployment’s API URL (the SDKs read `INTROSPECTION_BASE_API_URL`).
`--capabilities <list>`	Narrow the login’s data-plane and Git token to some of `runtimes`, `reviews`, `evals`, `git`; it can only take away.

Management commands act with your member role. Integrations, plan, and billing are dashboard-only, and a login cannot run automations (why).

Use an API key

Some commands accept a project API key through --token or INTROSPECTION_TOKEN, so they run in CI without a login (Credentials):

Accepts an API key	Always acts as your login
`tasks`, `conversations`, `events`, `metrics`, `files`, `shares`, `tags`, `images`, `annotations list`, `repositories contents`/`commits`/`commit` (these also need a login)	`runtimes`, `recipes`, `repositories list`/`add`/`remove`, `bindings`, `connectors`, `applications`, `api-keys`, `members`, `experiments`, `judges list`/`get`/`update`

An environment-scoped key only selects the environment. With a production key, tasks create, tasks delete, files upload and shares create still change production (files delete also needs the evals capability).

Diagnose and upgrade

Command	Does
`doctor [-o report]`	Reports CLI, Recipes, Pi, Node, and local recipe readiness; changes nothing.
`upgrade [--dry-run] [--format json] [--dismiss]`	Updates the CLI, Recipes, and Pi; `--dismiss` silences the notice until the next release.

Output flags

These flags work on every command:

Flag	Effect
`-o`, `--output`	`json` (default), `jsonc`, `table`, or `report`. `report` renders a report from `doctor`, `check`, and `eval` (the default for `eval` in a terminal); other commands fall back to `table`.
`--query`	A JMESPath expression applied before formatting.
`-y`, `--yes`	Answer every confirmation prompt with yes.
`--non-interactive`	Fail with the missing flag instead of waiting for terminal input.


introspection runtimes list -o table
introspection bindings endpoints list \
  --query "[?kind=='mcp'].{id:id,name:name,url:base_url}" -o table
introspection metrics query @q.json --query "data[0].metrics[0].value" -o table

-o table prints a single value bare, so --query id -o table gives a raw id.

Results go to stdout, progress to stderr. Exit codes: 0 success, 1 any failure (including API errors), 2 usage error, 3 a telemetry read rejected before the request. List commands return one page; follow --next, or use --page-all where a list offers it.

Command map

Step	Commands	Reference
Set up	`setup`, `skills`, `doctor`, `upgrade`, `login`, `logout`, `whoami`	This page
Build	`init`, `check`, `local`, `dev`, `open`, `recipes`	Develop locally
Ship	`runtimes`, `bindings`	Deploy & operate
Run	`tasks`	Deploy & operate
Debug	`conversations`, `events`, `metrics`, `annotations`	Evals & telemetry
Evaluate	`eval`, `judges`, `images`	Evals & telemetry
Experiment	`experiments`	Evals & telemetry
Administer	`api-keys`, `applications`, `members`, `repositories`, `connectors`, `files`, `shares`, `tags`, `automations`	Admin

Deploy & operate: runtimes, bindings, tasks.
Evals & telemetry: conversations, evals, judges, experiments.
Admin: keys, applications, members, connectors, files.