Local recipe commands

Use the commands on this page to create and test a recipe from your local files. For installation, setup, and login, start with CLI setup & login. For commands that manage cloud resources, see Project administration and Production signals & evals.

Create a recipe

introspection init creates a runnable recipe and its .introspection/ runtime manifest. It also creates a Git repository if you are not already in one. You do not need an Introspection account. Run the command without arguments to answer setup questions, or provide the recipe name and template in the command:

introspection init
introspection init support-agent
introspection init support-agent --template template-starter

You can run the new recipe with introspection local. The --template option selects a repository from the Introspection template catalog. If you omit the option, the CLI uses template-starter.

Validate recipes

introspection check checks a recipe without connecting to Introspection. It checks the runtime manifest, package metadata, agent YAML, and all declared agents, skills, extensions, included files, and file pattern boundaries.

# Discover every manifest under .introspection in the current workspace.
introspection check
 
# Validate a different workspace.
introspection check --work-dir ../support-agent
 
# Validate selected manifests. Repeat --path as needed.
introspection check \
  --path .introspection/support-agent.yaml \
  --path .introspection/refund-agent.yaml

The CLI reads each path relative to --work-dir. The command returns a nonzero exit code when a check fails.

Cloud recipe records identify the exact Git commit used to build a runtime. Manage those records with the recipes command group under project administration. See Recipe records.

Run a recipe locally

introspection local finds a runtime manifest in the repository and runs its recipe with Pi. Use --agent to select an agent by name. The CLI passes everything after -- to Pi without changing it.

introspection local [--runtime <NAME>] [--work-dir <DIRECTORY>] [--agent <NAME>]
                    [-p|--print <PROMPT>] [--mode <text|json>] [-- <PI_ARGS>...]

# Select the only runtime, or the one whose recipe contains this directory.
introspection local
 
# Select a runtime explicitly in a repository with several manifests.
introspection local --runtime support-agent
 
# Select an agent and run one prompt.
introspection local -r support-agent --agent triage \
  --print "Triage this refund request."

-p and --print <PROMPT> run one prompt and then exit. The --mode option requires --print. Choose text to return only the final assistant message, or choose json to return Pi’s structured event stream. The CLI returns an error if you provide either option before and after --.

The CLI starts in the current directory, or in the directory set by --work-dir <directory>. It searches parent directories for the nearest .introspection/ directory that contains YAML runtime manifests. Each manifest’s path must identify an existing recipe directory inside the repository, and that directory must contain package.json. Symbolic links cannot make the path leave the repository.

If the CLI finds more than one possible runtime, use --runtime with the manifest’s display name or filename without the extension. The --work-dir option changes where the CLI searches for manifests. Pi still runs from the directory where you started the CLI.

Before Pi starts, the CLI checks its requirements and validates every recipe manifest in the workspace. The check includes other manifests in the same repository. The CLI does not install missing tools, so run introspection setup if it reports that Pi or Recipes is not ready. Continue to manage model providers, sessions, trust settings, tools, and MCP through Pi.

introspection local runs without connecting to Introspection, so it does not use a login, project, cloud binding, or snapshot. The command uses your current terminal and environment, and it returns Pi’s exit status. It does not support the global --query option. Use --mode json to run one prompt and receive structured output:

introspection local -r support-agent --print "Triage this." --mode json
 
# Run a recipe from a different workspace.
introspection local --work-dir ../support-agent

Cloud-connected development

Run the following command from the Git working tree that contains your .introspection/<runtime-slug>.yaml manifest:

introspection dev

introspection dev connects your local recipe files to development tasks in Introspection. The command finds the runtime from the Git repository, unless you select one with --runtime. It then checks the cloud recipe and its declared MCP bindings, opens Runtime Preview, and watches your local files for changes. Introspection keeps each connection separate by project, member, and exact recipe commit.

Runtime Preview is the runtime’s development chat page in the dashboard. Its URL ends with …/runtimes/<runtime>/chat?environment=development. The CLI uses the local Git origin to find the page, and you can use the chat after the local session connects.

What a save changes

When you save a file, Introspection sends the change to the development sandbox. A task that is already running keeps its current agent session. The type of file you changed determines when you can see the new behavior:

If a change to system instructions does not appear, start a new task before you check the connection. Changes to runtime manifests do not take effect through the live connection to your working tree.

Run your application as usual with credentials for the development environment. The SDK run() call does not have an environment option. Project API keys, service account credentials, and federated customer sessions all use the same local recipe changes through their usual SDK calls. A federated task remains owned by the customer.

You can connect different recipe commits at the same time. If another machine or session has already connected the same agent and commit, the new connection fails with dev_slot_conflict. An interrupted CLI session can also leave a connection record behind. The record expires within about a minute, so the CLI waits briefly before returning the error. In a repository with several recipes, one process at the repository root can serve recipes whose runtimes use the same commit.

When several local sessions use the same development runtime, add --as NAME to give each connection a name. In your application process, set INTROSPECTION_DEV_TARGET to the exact target printed by the session you want to use. You can leave the variable unset when only one session is available.

The target setting works only with credentials for the development environment. If several sessions are available and you do not set a target, the request fails. A request also fails if the target does not exist, so Introspection will not send work to another developer’s session. Do not set the variable in staging or production.

By default, the CLI warns you about missing required or optional development bindings and continues. Use --check-bindings to return an error for a missing required binding and exit without connecting:

introspection dev --check-bindings
introspection dev --runtime support-agent
introspection dev --runtime support-agent --as John
 
# Route a declared MCP server to a local process during development.
introspection dev --mcp contacts=http://127.0.0.1:8787/mcp

The name after --mcp must match a server declared in the recipe. Your local process serves the MCP connection, while Introspection supplies credentials from the matching development binding. The CLI does not read local credential files, upload local secrets, or create endpoints.

You can also use the following options:

See the Agent development lifecycle for the steps from local Pi testing to production.

introspection eval run --from-conversation can load the context from a production conversation into a local run. See Replay production context.

Skills

introspection skills reads the current Introspection Agent Skills workflows. You or a coding agent can follow these workflows when working with Introspection. Run the command without a name to list the available workflows. Add a workflow name to print its instructions, or add a step name to print the instructions for that step:

introspection skills                   # list the available workflows
introspection skills create            # print one workflow
introspection skills create/scaffold   # print the context for one step
introspection skills --help            # dynamic help from the current manifest

The CLI downloads the official current workflow manifest and checks each content revision. It does not install the workflows or write to Codex or Claude Code directories, and you do not need to log in. If the CLI cannot refresh the index, it uses the most recent valid copy in its cache and reports the fallback on standard error. The CLI reads --help from the manifest, so you cannot use --help with a workflow name.

Open the dashboard

introspection open finds the runtime for the current recipe and opens it in the Introspection dashboard. You can select another runtime or open a specific task:

introspection open
introspection open --runtime support-agent
introspection open --task <task-id>
introspection open --print

The command always writes the URL to standard output. Add --print to print the URL without opening a browser.

Related

• CLI setup & login explains installation, setup, login, and command output.
• Production signals & evals explains how to run tasks and offline evaluations.
• Recipes explains the files and Git commits that define agent behavior.
• Agent development lifecycle explains the steps from local Pi testing to production.