Deploy & operate
These commands use your login; tasks also accepts
an API key. Concepts:
Runtimes, Bindings.
Runtimes
| Command | Does |
|---|---|
runtimes create [--manifest .introspection/<name>.yaml] | Creates version 1 from the pushed default-branch commit. It goes live in staging and production. |
runtimes list [--runtime <slug-or-group-id>] | Lists versions. |
runtimes get <version-id> | One version, with environments, environment_ref, runtime_group_id. |
runtimes versions <version-id> | Every version of that runtime. |
runtimes pin <version-id> [--sha <sha> | --branch <main|pr/N>] | Pins staging to that version, the version built from a commit, or a moving branch. |
runtimes unpin <version-id> | Staging returns to the default branch, and pull request previews can take it again. |
runtimes update <version-id> --yank [--reason <text>] / --unyank | Takes a version out of service (its environments move to the newest good build) or restores it. |
runtimes delete <version-id> | Deletes the whole runtime, every version. |
Every positional is a version id (the id from runtimes list). create
requires a clean worktree on the default branch, in sync with origin, which is
a GitHub repository the project’s integration reaches or a hosted repository;
later versions come from pushes, and a second create returns the existing
runtime. pin steers only staging; pin
production in the dashboard or with
PATCH /v1/runtimes/{version-id} (Roll back a release).
Bindings
introspection bindings endpoints list|get|create|update|delete
introspection bindings variables list|create|update|delete
introspection bindings credentials list|get|create|update|delete
introspection bindings mcp list|connect|disconnect| Flag | Meaning |
|---|---|
--runtime <slug-or-group-id> / --runtime-id <version-id> | Scope to a runtime or one version; omit for project-wide. |
--environment shared|development|staging|production | Scope to an environment; shared applies to all. On list, omitting it returns every row. |
--from-env <NAME> / --from-file <path|-> / --from-stdin | The only ways to pass a variable or credential value. |
--header 'Name=value ${CREDENTIAL}' | Endpoint header template; ${NAME} references a credential. |
--connector <id-or-slug> | Back an api or mcp endpoint with a connector’s connection. |
--authorized-application <application-uuid> | Send a signed JWT for the task’s end user instead of a stored token (Applications). |
@FILE | Whole endpoint document (JSON or YAML); flags override it. |
Reads never return secrets: credentials show has_secret, endpoints the
unresolved template. A connector or authorized application cannot be combined
with a stored Authorization header. bindings always acts on the login
project.
introspection bindings credentials create --name MCP_TOKEN --from-env MCP_TOKEN
introspection bindings mcp connect --mcp-server-id docs \
--endpoint-url https://mcp.example.com/mcp \
--header 'Authorization=Bearer ${MCP_TOKEN}'
introspection bindings mcp list --runtime support-agent --environment production--mcp-server-id must equal the server id in package.json#pi.mcp.servers;
connect does not check it, so confirm declared: true in mcp list with a
runtime and --environment. Without a runtime, mcp list shows the
project-wide bindings (--environment optional) with declared, required,
and tools empty. Endpoints need https on a public DNS
host. Walkthrough: Connect an MCP server.
Tasks
| Command | Does |
|---|---|
tasks create <target> [--prompt <text>] [flags] | Creates a task and its first run. |
tasks prompt <task-id> --prompt <text> [--file <id>] | New turn. |
tasks stream <task-id> [--run <id|current>] [--since <sequence>] | JSONL AG-UI events until the run settles. |
tasks resume <task-id> --interrupt-id <id> --payload '<json>' / --cancel-interrupt <id> | Answers every pending interrupt in one call. |
tasks cancel <task-id> | Aborts the turn; the task stays warm and idle (drain only via API or SDK). |
tasks list [--status <s>]... [--runtime-id <id>] [--limit <n>] [--next <cursor>] | One page (default 100). |
tasks get <task-id> / tasks runs get <task-id> <run-id> | The task (with metadata.pending_interrupts, metadata.latest_run_id) / one turn. |
tasks update <task-id> [--title <t>] [--metadata '<json>'] | Title; metadata merges. |
tasks archive|unarchive|delete <task-id> | Hide, restore, or delete (asks first). |
| Target | Version |
|---|---|
--runtime <slug> -e staging|production | The active version; automatic experiments apply. |
--runtime-id <version-id> -e <env> | In development, that exact version (reaches your introspection dev session at your commit); in staging and production, the runtime’s active version, as with --runtime. This is the form an API key must use. |
--experiment <id> --subject <stable-id> | The subject’s sticky arm. |
| Create flag | Effect |
|---|---|
--prompt <text | @path> | First prompt; @path uploads a file and sends its path. |
--agent <name> | Recipe agent to run. |
--subject <stable-id> | End user id (identity.user_id); see Run a task for an end user. |
--file <file-id[=path] | @path> | Attach a file, read-only under /workspace/files/ (repeatable). |
--repository <owner/name[@ref][:depth]> | Clone a registered repository into workspace/repos/. |
--idle-timeout <seconds> | Warm time between turns; 0 tears down after provisioning. |
--metadata <json> | Client metadata, including model and thinking_level overrides. |
--fork-share <share-id>, --tag <k:v>, --identity-tag <k:v> | Fork a shared conversation; tag the task; tag a new customer member. |
introspection tasks create --runtime support-agent -e staging --subject smoke-1 --prompt "Reply with ready."
introspection tasks stream <task-id>
introspection conversations get <task-id>There is no introspection run and no --wait. A local one-shot is
introspection local -p "Reply with ready." --mode text. stream is always
JSONL; a 410 means the history is gone, so read the conversation.
Next
- Roll back a release: pin and yank.
- Evals & telemetry: read what a task did.
- Task operations: statuses and interrupts.