Skip to content
Perstack

Running Experts

Running Experts

Section titled “Running Experts”

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

start vs run

Section titled “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

Section titled “perstack start”
Terminal window
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

Section titled “perstack run”
Terminal window
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

Section titled “Running registry Experts”

Run Experts from the registry using scoped names:

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

Common options

Section titled “Common options”
Terminal window
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

Section titled “What’s next”