Running Experts

Perstack provides two commands for running Experts: start and run.

start vs run

• perstack start — Interactive. A workbench for defining and testing Experts.
• perstack run — Headless. For production, automation, and scripting.

Both commands share the same options and execution behavior.

perstack start

npx perstack start my-expert "query"

Opens a text-based UI for iterating on Expert definitions:

• Watch execution in real-time
• Inspect tool calls and results
• Browse checkpoint history
• Continue with follow-up queries

Use perstack start while developing — refine your Expert’s instruction until it behaves as expected.

perstack run

npx perstack run my-expert "query"

Outputs JSON events to stdout. Each line is a JSON object representing an execution event.

Each invocation creates a new Job containing one or more Runs. See State Management for details on the execution hierarchy.

Use perstack run for:

• Production deployments
• CI/CD pipelines
• Automation scripts

Running registry Experts

Run Experts from the registry using scoped names:

npx perstack start tic-tac-toe "Let's play!"
npx perstack start @org/my-expert@1.0.0 "query"

Common options

npx perstack start my-expert "query" \
  --provider anthropic \
  --model claude-sonnet-4-5 \
  --max-steps 50

For the complete list of options, see CLI Reference.

What’s next

• State Management — Jobs, Runs, and checkpoints
• CLI Reference — all commands and options