Skip to main content

​
polpo init

Initialize Polpo in the current project. 
polpo init
Creates:
  • .polpo/polpo.json — configuration file with your team setup
  • .polpo/logs/ — log directory
  • .polpo/assessments/ — assessment results directory

​
polpo / polpo tui

Launch the interactive terminal UI. This is the default command — running polpo without arguments starts the TUI. 
polpo [options]
polpo tui [options]
OptionDefaultDescription
-d, --dir <path>.Path to working directory
See TUI Usage for details on features and commands.

​
polpo run

Execute all pending missions in headless mode. 
polpo run [options]
OptionDefaultDescription
-d, --dir <path>.Path to working directory containing .polpo/polpo.json
Output is streamed to stdout with color-coded status updates: 
[14:23:01] Polpo started — my-project
[14:23:01] Team agents: backend-dev, frontend-dev

[14:23:02] [task-1] Task added: Create database schema
[14:23:02] [task-1] Spawning "backend-dev" for: Create database schema
[14:24:15] [task-1] Agent finished — exit 0 (73.2s)
[14:24:18] [task-1] PASSED (score: 4.2/5) — All checks passed
[14:24:18] [task-1] DONE — Create database schema
The process exits when all tasks are done or failed.

​
polpo status

Show current task status as a dashboard. 
polpo status [options]
OptionDefaultDescription
-d, --dir <path>.Path to working directory
-w, --watchfalseAuto-refresh every 5 seconds
In watch mode, the display shows:
  • Progress bar with done/running/pending/failed counts
  • Per-task status with agent, elapsed time, PID
  • Live agent activity (current tool, file, tool call count)
  • G-Eval dimension scores for completed tasks (star ratings)
  • Failure reasons for failed tasks

​
polpo serve

Start the HTTP API server. 
polpo serve [options]
OptionDefaultDescription
-p, --port <port>3000Port to listen on
-H, --host <host>127.0.0.1Host to bind to
-d, --dir <path>.Path to working directory
--api-key <key>—API key for authentication (optional)
--project-id <id>dir nameProject ID
The server provides REST API, SSE streaming, and WebSocket support. See Server Usage for details.

​
polpo mission

Manage execution missions. 
polpo mission <subcommand> [options]
SubcommandDescription
listList all missions
show <missionId>Show mission details
create <prompt>Create a new mission with AI generation
execute <missionId>Execute a mission (create and run its tasks)
resume <missionId>Resume a paused or failed mission
delete <missionId>Delete a mission
abort <missionId>Abort all tasks in a mission
# Generate a mission from a prompt
polpo mission create "Build a REST API with auth and tests"

# List missions
polpo mission list

# Execute a specific mission
polpo mission execute <mission-id>

​
polpo task

Manage individual tasks. 
polpo task <subcommand> [options]
SubcommandDescription
listList all tasks (filter with --status or --group)
show <id>Show task details
add <description>Create a new task
retry <id>Retry a failed task
kill <id>Kill a running task
reassess <id>Re-run assessment on a completed task
delete <id>Remove a task

​
polpo team

Manage the agent team. 
polpo team <subcommand> [options]
SubcommandDescription
listList all agents
add <name>Add an agent (--model, --role)
remove <name>Remove an agent
rename <newName>Rename the team

​
polpo playbook

Manage and execute reusable mission playbooks. 
polpo playbook <subcommand> [options]
SubcommandDescription
listList all available playbooks
show <name>Show playbook details, parameters, and mission body
run <name>Execute a playbook with parameters
validate <name>Validate a playbook definition

​
polpo playbook run

polpo playbook run <name> [options]
OptionDefaultDescription
-d, --dir <path>.Working directory
-p, --param <key=value...>—Parameters as key=value pairs (repeatable)
--dry-runfalseShow the instantiated mission without executing
# Run a code review on the auth module
polpo playbook run code-review --param module=src/auth --param focus=security

# Preview what the mission would look like
polpo playbook run code-review --param module=src/auth --dry-run
See Playbooks for how to create your own.

​
polpo skills

Manage the skill pool — install, list, remove, and assign skills to agents. 
polpo skills <subcommand> [options]
SubcommandDescription
add <source>Install skills from a GitHub repo or local path
listList skills in the pool with agent assignments
remove <name>Remove a skill from the pool
assign <skill> <agent>Assign a skill to an agent
# Install all skills from a repo
polpo skills add vercel-labs/agent-skills

# Install specific skills
polpo skills add vercel-labs/agent-skills --skill frontend-design

# Assign to an agent
polpo skills assign frontend-design frontend-dev
Compatible with the skills.sh ecosystem — any repo with SKILL.md files works. See Skills for details.

​
Other Commands

CommandDescription
polpo memory [get|set|append]Project memory management
polpo logs [list|show|clear]Log management
polpo config [show|set|reload]Configuration management
polpo chatChat/conversation commands
polpo authAuthentication management
polpo modelsModel listing and management

​
Global Options

All commands accept the -d / --dir flag to specify the working directory. Polpo will look for .polpo/polpo.json in that directory. 
# Run from a different directory
polpo run -d /path/to/my-project

# Serve from a specific project
polpo serve -d ./projects/api-service --port 8080