perstack

The Command Line Interface (CLI) for Perstack. Run Experts interactively or in headless mode.

For full documentation, see Perstack Documentation.

Installation

You can run perstack directly using npx:

npx perstack [command]

Or install it globally:

npm install -g perstack

Usage

start: Interactive Mode

Starts an interactive TUI session.

perstack start [expert] [query]

run: Headless Mode

Executes an agent run and outputs JSON events to stdout.

perstack run <expert> <query>

Shared Options

| Option | Description | Default | | ------------------------------------ | -------------------------------------- | -------------------- | | --config <path> | Path to perstack.toml | Auto-discover | | --provider <provider> | LLM provider | anthropic | | --model <model> | Model name | claude-sonnet-4-5 | | --max-retries <n> | Max retry attempts | 5 | | --timeout <ms> | Timeout per generation | 300000 | | --reasoning-budget <budget> | Reasoning budget for native LLM reasoning | - | | --job-id <id> | Custom job ID | auto-generated | | --env-path <path...> | Environment file paths | .env, .env.local | | --continue | Continue latest job | - | | --continue-job <id> | Continue specific job | - | | --resume-from <id> | Resume from checkpoint | - | | -i, --interactive-tool-call-result | Query is tool call result | - | | --filter <types> | Filter events by type (run only) | - | | --verbose | Enable verbose logging | - |

Configuration

Perstack is configured via a perstack.toml file in your project root.

# perstack.toml
model = "claude-sonnet-4-5"

[provider]
providerName = "anthropic"

[experts."researcher"]
description = "Researches topics using web search"
instruction = "You are an expert researcher..."

[experts."researcher".skills."web-search"]
type = "mcpStdioSkill"
command = "npx"
packageName = "exa-mcp-server"
requiredEnv = ["EXA_API_KEY"]

Environment Variables

Secrets like API keys should be stored in a .env file:

ANTHROPIC_API_KEY=sk-...
OPENAI_API_KEY=sk-...
PERSTACK_API_KEY=...

Development

This package is part of the Perstack monorepo. To build and run locally:

bun install
bun run build
bun dist/bin/cli.js start