CLI Reference

Command Overview

perstack
├── start          Interactive TUI for developing and testing experts
├── run            Headless execution with JSON event output
├── log            View execution history and events
├── install        Pre-collect tool definitions for faster startup
├── expert         Manage experts on Perstack API
│   ├── list       List draft scopes
│   ├── create     Create a new draft scope
│   ├── delete     Delete a draft scope
│   ├── push       Push local expert definitions to a draft ref
│   ├── refs       List draft refs
│   ├── version    Assign a version to a draft ref
│   ├── versions   List published versions
│   ├── publish    Make an expert scope public
│   ├── unpublish  Make an expert scope private
│   └── yank       Deprecate a specific version
└── application    Manage applications on Perstack API
    └── list       List applications

Running Experts

perstack start

Interactive workbench for developing and testing experts.

perstack start [expertKey] [query] [options]

Arguments:

Argument	Required	Description
[expertKey]	No	Expert key (prompts if not provided)
[query]	No	Input query (prompts if not provided)

perstack run

Headless execution for production and automation. Outputs JSON events to stdout.

perstack run <expertKey> <query> [options]

Arguments:

Argument	Required	Description
<expertKey>	Yes	Expert key (e.g., my-expert, @org/my-expert, @org/expert@1.0.0)
<query>	Yes	Input query

run-only option:

Option	Description
--filter <types>	Filter events by type (comma-separated, e.g., completeRun,stopRunByError)

Shared Options

Both start and run accept the following options:

Model and Provider

Option	Default	Description
--provider <provider>	anthropic	LLM provider
--model <model>	auto	Model name (auto-resolved from expert tier or provider’s middle tier)
--reasoning-budget <budget>	-	Reasoning budget (minimal, low, medium, high, or token count)

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

Execution Control

Option	Default	Description
--max-retries <n>	5	Max retry attempts per generation
--timeout <ms>	300000	Timeout per generation (ms)

Configuration

Option	Default	Description
--config <path>	Auto-discover from cwd	Path or HTTPS URL to perstack.toml
--env-path <path...>	.env, .env.local	Environment file paths

Job and Run Management

Option	Description
--job-id <id>	Custom job ID (default: auto-generated)
--continue	Continue latest job with new run
--continue-job <id>	Continue specific job with new run
--resume-from <id>	Resume from specific checkpoint (requires --continue-job)

# Continue latest job from its latest checkpoint
--continue

# Continue specific job from its latest checkpoint
--continue-job <jobId>

# Continue specific job from a specific checkpoint
--continue-job <jobId> --resume-from <checkpointId>

--resume-from requires --continue-job. You can only resume from the coordinator expert’s checkpoints.

Interactive

Option	Description
-i, --interactive-tool-call-result	Treat query as interactive tool call result

Use with --continue to respond to interactive tool calls from the coordinator expert.

Other

Option	Description
--verbose	Enable verbose logging

Debugging and Inspection

perstack log

View execution history and events for debugging.

perstack log [options]

When called without options, shows a summary of the latest job (max 100 events).

Options:

Option	Default	Description
--job <jobId>	-	Show events for a specific job
--run <runId>	-	Show events for a specific run
--checkpoint <id>	-	Show checkpoint details
--step <step>	-	Filter by step number (e.g., 5, >5, 1-10)
--type <type>	-	Filter by event type
--errors	-	Show only error-related events
--tools	-	Show only tool call events
--delegations	-	Show only delegation events
--filter <expression>	-	Simple filter expression
--json	-	Output as JSON
--pretty	-	Pretty-print JSON output
--verbose	-	Show full event details
--take <n>	100	Number of events to display (0 for all)
--offset <n>	0	Number of events to skip
--context <n>	-	Include N events before/after matches
--messages	-	Show message history for checkpoint
--summary	-	Show summarized view

Event types:

startRun, callTools, resolveToolResults, callDelegate, stopRunByError, retry, completeRun, continueToNextStep

Filter expression syntax:

--filter '.type == "completeRun"'
--filter '.stepNumber > 5'
--filter '.toolCalls[].skillName == "base"'

Step range syntax:

--step 5       # Exact step
--step ">5"    # Greater than 5
--step ">=5"   # Greater than or equal to 5
--step "1-10"  # Range (inclusive)

Performance Optimization

perstack install

Pre-collect tool definitions to enable instant LLM inference.

perstack install [options]

By default, Perstack initializes MCP skills at runtime to discover their tool definitions. This can add 500ms-6s startup latency per skill. perstack install solves this by:

1. Initializing all skills once and collecting their tool schemas
2. Caching the schemas in a perstack.lock file
3. Enabling the runtime to start LLM inference immediately using cached schemas
4. Deferring actual MCP connections until tools are called

Options:

Option	Default	Description
--config <path>	Auto-discover from cwd	Path or HTTPS URL to perstack.toml
--env-path <path...>	.env, .env.local	Environment file paths

The lockfile is optional. If not present, skills are initialized at runtime.

Expert Management

The expert command group manages experts on the Perstack API.

perstack expert <subcommand> [options]

Parent options (inherited by all subcommands):

Option	Default	Description
--api-key <key>	PERSTACK_API_KEY env var	API key
--base-url <url>	https://api.perstack.ai	API base URL

expert list

List draft scopes.

perstack expert list [options]

Option	Description
--filter <name>	Filter by name
--take <n>	Limit results
--skip <n>	Offset

expert create

Create a new draft scope.

perstack expert create <scopeName> --app <id>

Argument	Required	Description
<scopeName>	Yes	Expert scope name

Option	Required	Description
--app <id>	Yes	Application ID

expert delete

Delete a draft scope.

perstack expert delete <draftScopeId>

Argument	Required	Description
<draftScopeId>	Yes	Draft scope ID

expert push

Push local expert definitions to a draft ref.

perstack expert push <draftScopeId> [options]

Argument	Required	Description
<draftScopeId>	Yes	Draft scope ID

Option	Description
--config <path>	Path or HTTPS URL to perstack.toml

Reads experts from perstack.toml and creates a new draft ref.

expert refs

List draft refs for a draft scope.

perstack expert refs <draftScopeId> [options]

Argument	Required	Description
<draftScopeId>	Yes	Draft scope ID

Option	Description
--take <n>	Limit results
--skip <n>	Offset

expert version

Assign a semantic version to a draft ref.

perstack expert version <draftScopeId> <refId> <version> [options]

Argument	Required	Description
<draftScopeId>	Yes	Draft scope ID
<refId>	Yes	Draft ref ID
<version>	Yes	Semantic version (e.g., 1.0.0)

Option	Description
--tag <tag>	Version tag (e.g., latest)
--readme <path>	Path to README file

expert versions

List published versions for an expert scope. Does not require an API key for public experts.

perstack expert versions <scopeName>

Argument	Required	Description
<scopeName>	Yes	Expert scope name

expert publish

Make an expert scope public.

perstack expert publish <scopeName>

Argument	Required	Description
<scopeName>	Yes	Expert scope name

expert unpublish

Make an expert scope private.

perstack expert unpublish <scopeName>

Argument	Required	Description
<scopeName>	Yes	Expert scope name

expert yank

Deprecate a specific expert version.

perstack expert yank <key>

Argument	Required	Description
<key>	Yes	Expert key with version (e.g., my-expert@1.0.0)

Application Management

The application command group manages applications on the Perstack API.

perstack application <subcommand> [options]

Parent options (inherited by all subcommands):

Option	Default	Description
--api-key <key>	PERSTACK_API_KEY env var	API key
--base-url <url>	https://api.perstack.ai	API base URL

application list

List applications.

perstack application list

Environment Variables

Variable	Description
PERSTACK_API_KEY	API key for expert and application commands
PERSTACK_STORAGE_PATH	Storage directory for job/run data (default: ./perstack)

Examples

# Basic execution
perstack run my-expert "Review this code"

# Interactive TUI
perstack start

# With model options
perstack run my-expert "query" --provider google --model gemini-2.5-pro

# Continue job with follow-up
perstack run my-expert "initial query"
perstack run my-expert "follow-up" --continue

# Continue specific job from specific checkpoint
perstack run my-expert "retry" --continue-job job_abc --resume-from cp_xyz

# Respond to interactive tool call
perstack run my-expert "user response" --continue -i

# Custom config and env
perstack run my-expert "query" --config ./production.toml --env-path .env.production

# Registry experts
perstack run @org/expert@1.0.0 "query"

# Generate lockfile
perstack install

# List applications
perstack application list

# Expert lifecycle
perstack expert create my-expert --app <applicationId>
perstack expert push <draftScopeId> --config ./perstack.toml
perstack expert version <draftScopeId> <refId> 1.0.0 --tag latest
perstack expert versions my-expert
perstack expert publish my-expert
perstack expert yank my-expert@1.0.0
perstack expert unpublish my-expert
perstack expert delete <draftScopeId>

# View execution logs
perstack log
perstack log --job abc123 --errors --context 5
perstack log --json --pretty