/Recipes
Docs

Recipe CLI

recipes installs and manages Pi recipes. Use it to install shared recipes, register local folders, validate manifests, create starter recipes, customize installed recipes, and publish your own Git-backed agent systems.

Install Pi first and confirm pi is on PATH. Pi Recipes currently requires Node.js 24 or later; check node --version before installation.

recipes --help

Mental model

Installed recipes live in a local recipe store. Remote Git recipes are cloned into that store; local recipes are registered by path, so edits to the folder are visible the next time Pi starts. Pi then resolves --recipeinto a folder, selects an agent, and loads package-wide prompts plus the effective agent's model profile, skills, tools, extensions, and connection policy into the session.

Commands

  • recipes setup installs the companion Pi extension.
  • recipes create ./my-recipe scaffolds a starter recipe.
  • recipes install owner/repo#ref installs a selected remote recipe; use a commit SHA or protected release tag for reproducibility. recipes install ./my-recipe registers a local one.
  • recipes customize <name> creates an editable copy.
  • recipes list shows installed recipes.
  • recipes path <name>prints a recipe's directory.
  • recipes check <name> validates the manifest and resources.
  • recipes remove <name> removes a recipe from the store.
  • recipes publish ./my-recipe --github owner/repo publishes a recipe.

Common flow

npm install -g @introspection-ai/pi-recipes
recipes install owner/repo#0.1.0
recipes list
pi --recipe recipe-name

Store

Recipes are tracked in a local store:

~/.pi/recipes/recipes.json

Use a different store with an env var or flag:

PI_RECIPES_HOME=/path/to/store recipes list
recipes list --store /path/to/store

Create a recipe

recipes create ./my-recipe

This writes a working skeleton:

my-recipe/
  package.json
  README.md
  SYSTEM.md
  agents/
    agent.yaml

Develop a recipe

Validate the current recipe directory with check, then register and run it. This is the fastest loop for authoring recipe behavior locally.

recipes check .
recipes install ./my-recipe
recipes list
pi --recipe my-recipe

Publish a recipe

Publishing validates the folder, pushes it to GitHub, and makes the same recipe installable by anyone with access to the repository.

recipes publish ./my-recipe --github owner/my-recipe --visibility public
git -C ./my-recipe rev-parse HEAD
recipes install owner/my-recipe#<commit-sha-from-above>

recipes publish pushes the current commit but does not print its SHA or create a release tag. Read the pushed commit with git rev-parse HEAD for a reproducible install, or create and protect a release tag through your Git workflow.