CLI Reference

Running Experts

perstack start

Interactive workbench for developing and testing Experts.

perstack start [expertKey] [query] [options]

Arguments:

• [expertKey]: Expert key (optional — prompts if not provided)
• [query]: Input query (optional — prompts if not provided)

Opens a text-based UI for iterating on Expert definitions. See Running Experts.

perstack run

Headless execution for production and automation.

perstack run <expertKey> <query> [options]

Arguments:

• <expertKey>: Expert key (required)
  • Examples: my-expert, @org/my-expert, @org/my-expert@1.0.0
• <query>: Input query (required)

Outputs JSON events to stdout.

Shared Options

Both start and run accept the same options:

Model and Provider

Providers: anthropic, google, openai, ollama, azure-openai, amazon-bedrock, google-vertex

Execution Control

Configuration

Run Management

Interactive

Use with --continue to respond to interactive tool calls.

Other

Examples

# Basic execution
npx perstack run my-expert "Review this code"
 
# With model options
npx perstack run my-expert "query" \
  --provider google \
  --model gemini-2.5-pro \
  --temperature 0.7 \
  --max-steps 100
 
# Continue execution
npx perstack run my-expert "initial query"
npx perstack run my-expert "follow-up" --continue
 
# Continue specific run
npx perstack run my-expert "continue" --continue-run abc123
 
# Custom config
npx perstack run my-expert "query" \
  --config ./configs/production.toml \
  --env-path .env.production
 
# Registry Experts
npx perstack run tic-tac-toe "Let's play!"
npx perstack run @org/expert@1.0.0 "query"

Registry Management

perstack publish

Publish an Expert to the registry.

perstack publish [expertName] [options]

Arguments:

• [expertName]: Expert name from perstack.toml (prompts if not provided)

Options:

Example:

perstack publish my-expert
perstack publish my-expert --dry-run

Requires PERSTACK_API_KEY environment variable.

Note: Published Experts must use npx or uvx as skill commands. Arbitrary commands are not allowed for security reasons. See Publishing.

perstack unpublish

Remove an Expert version from the registry.

perstack unpublish [expertKey] [options]

Arguments:

• [expertKey]: Expert key with version (e.g., my-expert@1.0.0)

Options:

Example:

perstack unpublish                          # Interactive mode
perstack unpublish my-expert@1.0.0 --force  # Non-interactive

perstack tag

Add or update tags on an Expert version.

perstack tag [expertKey] [tags...] [options]

Arguments:

• [expertKey]: Expert key with version (e.g., my-expert@1.0.0)
• [tags...]: Tags to set (e.g., stable, beta)

Options:

Example:

perstack tag                              # Interactive mode
perstack tag my-expert@1.0.0 stable beta  # Set tags directly

perstack status

Change the status of an Expert version.

perstack status [expertKey] [status] [options]

Arguments:

• [expertKey]: Expert key with version (e.g., my-expert@1.0.0)
• [status]: New status (available, deprecated, disabled)

Options:

Example:

perstack status                           # Interactive mode
perstack status my-expert@1.0.0 deprecated