CLI - Polpo

Running polpo with no arguments launches the TUI. All commands that interact with a project accept -d, --dir <path> to set the working directory (defaults to .).

polpo init

Initialize Polpo in the current project. Creates .polpo/ with polpo.json, logs/, and assessments/.

polpo init

polpo run

Execute pending tasks. Streams color-coded status updates and exits when all tasks are done or failed.

polpo run [-d <path>]

polpo status

Show current task status as a live dashboard with progress bar, per-task status, agent activity, scores, and failure reasons.

polpo status [-d <path>] [-w]

Flag	Description
`-w, --watch`	Auto-refresh every 2 seconds

polpo serve

Start the HTTP API server with REST, SSE, and WebSocket support.

polpo serve [-p <port>] [-H <host>] [-d <path>] [--api-key <key>] [--project-id <id>]

Flag	Default	Description
`-p, --port`	`3000`	Port to listen on
`-H, --host`	`127.0.0.1`	Host to bind to
`--api-key`	—	API key for authentication
`--project-id`	dir name	Project ID

polpo tui

Launch the interactive TUI. This is the default command.

polpo tui [-d <path>]
polpo          # same thing

polpo chat

Send a one-shot message to the Polpo assistant about your project. Maintains session history (30-minute timeout, max 20 messages).

polpo chat <message...> [-d <path>]

polpo task

Manage tasks.

task list

polpo task list [-d <path>] [--status <status>] [--group <group>]

Flag	Description
`--status`	Filter by task status
`--group`	Filter by mission group

task show

polpo task show <taskId> [-d <path>]

Shows title, status, agent, group, dependencies, retries, description, result (stdout/stderr), and assessment scores. <taskId> supports prefix matching.

task add

polpo task add <description...> [-d <path>] [-a <agent>] [--no-prep]

Flag	Description
`-a, --agent`	Assign to a specific agent
`--no-prep`	Skip LLM task-prep, create directly

task retry

polpo task retry <taskId> [-d <path>]

task kill

polpo task kill <taskId> [-d <path>]

task reassess

Re-run assessment on a completed task.

polpo task reassess <taskId> [-d <path>]

task delete

polpo task delete <taskId> [-d <path>]

polpo mission

Manage execution missions.

mission list

polpo mission list [-d <path>]

mission show

polpo mission show <missionId> [-d <path>]

Shows name, status, prompt, timestamps, and raw mission data. <missionId> accepts ID or name.

mission create

Generate a mission from a prompt using the LLM.

polpo mission create <prompt...> [-d <path>] [--execute] [--save]

Flag	Description
`--execute`	Execute immediately after creation
`--save`	Save as draft (default when `--execute` is not given)

mission execute

polpo mission execute <missionId> [-d <path>]

mission resume

polpo mission resume <missionId> [-d <path>] [--no-retry-failed]

Flag	Description
`--no-retry-failed`	Do not retry failed tasks

mission delete

polpo mission delete <missionId> [-d <path>]

mission abort

Abort all tasks in a mission group.

polpo mission abort <group> [-d <path>]

polpo team

Manage the agent team.

team list

polpo team list [-d <path>]

team add

polpo team add <name> [-d <path>] [-m <model>] [-r <role>]

Flag	Description
`-m, --model`	Model ID
`-r, --role`	Agent role description

team remove

polpo team remove <name> [-d <path>]

team rename

polpo team rename <newName> [-d <path>]

polpo agent

Agent identity and management commands.

agent onboard

polpo agent onboard <name> [-d <path>]

Interactive wizard to set up an agent’s full profile. Walks through 5 steps:

Identity — display name, title, company, email, timezone, bio
Persona — structured responsibilities (area + description + priority), communication tone, personality traits
Hierarchy — reportsTo assignment (org chart parent for escalation)
Email — SMTP vault entry (send) and IMAP vault entry (read), adds email_* to allowedTools
Vault — additional credentials (API keys, OAuth tokens, logins, custom)

Agent config is saved to .polpo/polpo.json; vault entries are saved to .polpo/vault.enc (AES-256-GCM encrypted). Run again to update an existing agent’s profile. See Onboarding walkthrough for detailed examples of each step.

agent list

polpo agent list [-d <path>]

Show all agents as an org chart tree with roles, enabled tools, and vault status.

agent show

polpo agent show <name> [-d <path>]

Detailed view of an agent: identity, vault (credentials masked), and enabled features.

polpo browser

Manage persistent browser profiles for agents with browser tools. Open a visible browser with the agent’s profile for manual login. The session (cookies, localStorage) is saved to .polpo/browser-profiles/<profileName>/ and reused automatically when the agent runs tasks.

polpo browser login <agent> [url] [-d <path>]

Flag	Default	Description
`url`	`https://x.com/login`	URL to open for login

browser list

List all browser profiles with last-used timestamps and session status.

polpo browser list [-d <path>]

browser clear

Delete an agent’s browser profile (removes all saved cookies and sessions).

polpo browser clear <agent> [-d <path>] [-f]

Flag	Description
`-f, --force`	Skip confirmation

polpo memory

View and manage project memory.

memory show

polpo memory show [-d <path>]

memory set

Replace the entire project memory.

polpo memory set <content...> [-d <path>]

memory append

Append a line to the project memory.

polpo memory append <line...> [-d <path>]

memory edit

Open project memory in $EDITOR (defaults to vi).

polpo memory edit [-d <path>]

polpo logs

View persistent event logs.

logs list

polpo logs list [-d <path>]

logs show

polpo logs show [sessionId] [-d <path>] [-n <limit>] [--event <pattern>]

Flag	Default	Description
`-n, --limit`	`50`	Max entries to show
`--event`	—	Filter by event name (substring match)

If sessionId is omitted, uses the current active session.

polpo config

Configuration management.

config show

polpo config show [-d <path>]

Shows project name, version, team, settings, and agents table.

config validate

polpo config validate [-d <path>]

Validates .polpo/polpo.json. Exits with code 0 on valid, 1 on invalid.

polpo playbook

Manage reusable mission playbooks.

playbook list

polpo playbook list [-d <path>]

playbook show

polpo playbook show <name> [-d <path>]

playbook run

polpo playbook run <name> [-d <path>] [-p key=value...] [--dry-run]

Flag	Description
`-p, --param`	Parameters as `key=value` pairs (repeatable)
`--dry-run`	Show the instantiated mission without executing

playbook validate

Validate a playbook definition (checks fields, tasks, placeholders, unused params).

polpo playbook validate <name> [-d <path>]

polpo skills

Manage the skill pool.

skills add

Install skills from a GitHub repo or local path.

polpo skills add <source> [-d <path>] [-s <names...>] [-g] [-f]

Flag	Description
`-s, --skill`	Install only specific skill names
`-g, --global`	Install to `~/.polpo/skills/` (shared across projects)
`-f, --force`	Overwrite existing skills

skills list

polpo skills list [-d <path>]
polpo skills ls               # alias

skills remove

polpo skills remove <name> [-d <path>] [-g]
polpo skills rm <name>         # alias

Flag	Description
`-g, --global`	Remove from `~/.polpo/skills/`

skills assign

Assign a skill to an agent (creates symlink).

polpo skills assign <skill> <agent> [-d <path>]

skills orchestrator list

List orchestrator skills (from .polpo/.agent/skills/).

polpo skills orchestrator list [-d <path>]

skills orchestrator add

Install skills into the orchestrator’s pool.

polpo skills orchestrator add <source> [-s <names...>] [-f] [-d <path>]

Flag	Description
`-s, --skill <names...>`	Install only specific skills
`-f, --force`	Overwrite existing skills

skills orchestrator remove

Remove a skill from the orchestrator’s pool.

polpo skills orchestrator remove <name> [-d <path>]

polpo ink

Manage the Ink Hub — install, list, update, and remove packages from git-native registries.

ink add

Install packages from a registry source.

polpo ink add <source> [-d <path>] [-y] [--list]

<source> can be an owner/repo shorthand, a full GitHub URL, or a local path.

Flag	Description
`-y, --yes`	Skip confirmation prompts
`--list`	List available packages without installing

ink list

List installed packages from ink.lock.

polpo ink list [-d <path>]
polpo ink ls          # alias

ink remove

Remove an installed registry and all its packages.

polpo ink remove <source> [-d <path>]
polpo ink rm <source> # alias

ink update

Update installed registries to latest (pulls, re-discovers, shows diff).

polpo ink update [source] [-d <path>] [-y]

Flag	Description
`[source]`	Update a specific registry (default: all)
`-y, --yes`	Skip confirmation prompts

polpo auth

Manage OAuth authentication for LLM providers.

polpo auth login [provider]

If provider is omitted, shows an interactive picker.

auth status

Show all stored OAuth profiles and their status (active/expired, expiry, email, last used).

polpo auth status

auth logout

polpo auth logout [provider] [--all]

Flag	Description
`--all`	Remove all stored credentials

polpo models

Manage models and LLM providers.

models list

polpo models list [--provider <name>] [--all] [--json] [--plain]

Flag	Description
`--provider`	Filter by provider name
`--all`	Show all models (not just top 5 per provider)
`--json`	Output as JSON
`--plain`	One model per line, `provider:id` format

models status

Show resolved model configuration, fallback chain, per-provider auth status, and active cooldowns.

polpo models status [-d <path>] [--json] [--check] [--plain]

Flag	Description
`--json`	Output as JSON
`--check`	Exit code 1 if auth missing/expired, 2 if expiring soon
`--plain`	Print only the resolved primary model

models scan

Scan for locally running model servers (Ollama, vLLM, LM Studio, LocalAI, LiteLLM Proxy, TGI).

polpo models scan [--json] [--timeout <ms>]

Flag	Default	Description
`--json`	—	Output as JSON
`--timeout`	`3000`	Connection timeout per endpoint (ms)

Core Reference

Backends

Development

​polpo init

​polpo run

​polpo status

​polpo serve

​polpo tui

​polpo chat

​polpo task

​task list

​task show

​task add

​task retry

​task kill

​task reassess

​task delete

​polpo mission

​mission list

​mission show

​mission create

​mission execute

​mission resume

​mission delete

​mission abort

​polpo team

​team list

​team add

​team remove

​team rename

​polpo agent

​agent onboard

​agent list

​agent show

​polpo browser

​browser login

​browser list

​browser clear

​polpo memory

​memory show

​memory set

​memory append

​memory edit

​polpo logs

​logs list

​logs show

​polpo config

​config show

​config validate

​polpo playbook

​playbook list

​playbook show

​playbook run

​playbook validate

​polpo skills

​skills add

​skills list

​skills remove

​skills assign

​skills orchestrator list

​skills orchestrator add

​skills orchestrator remove

​polpo ink

​ink add

​ink list

​ink remove

​ink update

​polpo auth

​auth login

​auth status

​auth logout

​polpo models

​models list

​models status

​models scan