Command Reference

Run polpo <command> --help for the installed build’s authoritative option list.

Cloud project setup

`polpo create`

polpo create [--name <name>] [--org-id <id>] [--template <id>] \
  [--scenario <id>] [--api-url <url>] [--skills <scope>] \
  [--install-cli <yes|no>] [--env <development|production>] [--prod] [-y, --yes]

Template IDs are empty, chat, chat-widget, and multi-agent. Scenario IDs are none, data-analyst, marketing-researcher, and product-manager. Skill scope is global, project, or skip.

`polpo link`

Links a directory, pulls the project resources, writes .polpo/project.json, and creates local environment configuration.

polpo link --project-id <uuid> [-d, --dir <path>] [--api-url <url>] \
  [--env <development|production>] [--prod] [-y, --yes]

`polpo migrate`

Converts legacy aggregate project files to the directory-based project layout. Migration is explicit: normal CLI and runtime operations continue to read legacy projects without rewriting them.

polpo migrate [--dir <path>] [--dry-run]

Run with --dry-run first to validate every agent, team, and destination path. A successful migration writes one directory per agent and one file per team, moves a legacy polpo.json config to project.json when present, and retains the original aggregate files as *.v1.json backups.

`polpo install`

polpo install [--client <ids>] [--scope <global|project>] \
  [-d, --dir <path>] [--api-url <url>] [-i, --interactive]

Known client IDs include claude-code, cursor, codex, copilot, windsurf, cline, trae, roo-code, qoder, and opencode.

Authentication

polpo login [--api-key <key>] [--url <base-url>] [--dashboard-url <url>] [--no-browser]
polpo logout
polpo whoami [--json]

Deployment

polpo deploy synchronizes the local .polpo/ project to Cloud, including agents, teams, skills, runtime hook packs, memory, missions, playbooks, schedules, vault metadata, loop definitions, custom tools, and avatars when present.

polpo deploy [--dir <path>] [--yes] [--force] [--include-tasks] \
  [--include-sessions] [--all] \
  [--env <development|production>] [--prod]

--all imports tasks and sessions. There is no run-history deploy option. --force overrides supported remote resources without prompting. Project commands default to Development on every invocation. Use --prod or --env production explicitly for Production. The target is not persisted in .polpo/project.json, and --prod --env development is rejected. The same environment options apply to tools, Connections, Channels, volumes, Memory, BYOK, Data, status, logs, and skill commands that deploy.

Custom tools

Custom tools are TypeScript files that default-export defineTool(...).

polpo tools push <file> [--name <snake_case_name>] [--env <development|production>] [--prod]
polpo tools list [--env <development|production>] [--prod]
polpo tools get <name> [--env <development|production>] [--prod]
polpo tools run <name> [--args '{"key":"value"}'] [--env <development|production>] [--prod]
polpo tools rm <name> [--env <development|production>] [--prod]
polpo tools remove <name> [--env <development|production>] [--prod]

run --args must be a JSON object. rm and remove are aliases.

Runtime hooks

polpo hooks validate [--dir <project-path>]
polpo hooks list --local [--dir <project-path>]
polpo hooks list [--env <development|production>] [--prod]

Hook packs live in .polpo/hooks/<name>.json; the filename and pack name must match. polpo deploy validates and uploads packs before the agents that reference them.

Active Run steering

polpo runs steer <run-id> --message <text> \
  [--id <idempotency-key>] [--mode <steer|follow_up>] [--locale <bcp47>] \
  [--env <development|production>] [--prod] [--json]
polpo runs steering get <run-id> <message-id> \
  [--env <development|production>] [--prod] [--json]
polpo runs abort <run-id> [--reason <text>] \
  [--env <development|production>] [--prod] [--json]

steer submits a durable instruction for the next safe agent boundary. follow_up waits until the Run would otherwise finish. Reuse --id when retrying an uncertain request, then inspect whether delivery became delivered, too_late, cancelled, or failed with steering get.

Connections

polpo connections list [--provider <provider>] [--status <status>] [--json] [--env <development|production>] [--prod]
polpo connections grants [--agent <name>] [--connection <id>] [--status <status>] [--json]
polpo connections bind <connection-id> (--binding <json> | --clear) [--json]
polpo connections grant-slot <connection-id> --agent <name> --tool <name> [--scope <scopes...>] [--json]
polpo connections revoke-slot <grant-id> [--json]
polpo connections readiness --agent <name> --tool <name> --slot <name> \
  [--provider <provider>] [--scope <scopes...>] [--user <id>] \
  [--metadata <json>] [--scope-key <key>] [--scope-version <version>] [--json]

These commands manage non-secret bindings and grants. They never accept or print access tokens, API keys, passwords, or provider credentials.

Sandbox volumes

polpo volumes list [--json]
polpo volumes get <name> [--json]
polpo volumes create <name> --strategy <mounted|hydrated> \
  [--label <label>] [--access <read-only|read-write>] \
  [--write-back <auto|manual>] [--mount-path <path>] [--json]
polpo volumes update <name> [--strategy <mounted|hydrated>] \
  [--label <label> | --clear-label] \
  [--access <read-only|read-write>] \
  [--write-back <auto|manual> | --clear-write-back] \
  [--mount-path <path> | --default-mount-path] [--json]
polpo volumes remove <name> [--yes] [--json]

polpo volumes grants list --agent <name> [--json]
polpo volumes grants set <volume> --agent <name> \
  [--access <read-only|read-write>] [--write-back <auto|manual>] [--json]
polpo volumes grants revoke <volume> --agent <name> [--yes] [--json]

Every volume command also accepts --env <development|production> and --prod. The catalog defines the maximum volume policy. A grant can only preserve or narrow that policy. Runtime sandbox.volumes selections may narrow it again, but cannot create a volume, add a grant, change its mount path, or widen access. Deletion and revocation require confirmation; use --yes only in deliberate non-interactive automation.

Agentic loops

polpo loops validate [--dir <project-path>]
polpo loops compile [file] [--dir <project-path>] [-o, --out <file>]

validate checks JSON and TypeScript definitions under .polpo/loops. compile emits canonical loop JSON; --out is valid only when compiling one source file.

BYOK

polpo byok set <provider> [--key <key>] [--label <label>] [--project <project-id>] [--env <development|production>] [--prod]
polpo byok list [--project <project-id>] [--env <development|production>] [--prod]
polpo byok remove <provider> [--env <development|production>] [--prod]

Projects and organizations

polpo projects list [--org <org-id>]
polpo projects create <name> [--org <org-id>]
polpo orgs list [--json]

Cloud monitoring

polpo cloud-status [--dir <path>] [--env <development|production>] [--prod]
polpo cloud-logs [--follow] [--dir <path>] [--env <development|production>] [--prod]

Local runtime

The OSS CLI also exposes local project operations:

Command	Purpose
`polpo create`	Create or link a project and initialize `.polpo/`
`polpo start` / `polpo serve`	Start the API and dashboard
`polpo run`	Execute pending tasks
`polpo status`	Show task status
`polpo task`, `mission`, `team`, `agent`	Manage runtime resources
`polpo memory`, `logs`, `config`	Inspect local state and configuration
`polpo playbook`, `skills`, `models`, `schedule`, `browser`	Manage supporting resources

Update

polpo update [--check]
polpo upgrade [--check]

update and upgrade are aliases.

Application databases

polpo data list [--env <development|production>] [--prod]
polpo data describe crm
polpo data create database.json
polpo data execute crm operations.json
polpo data query crm query.json
polpo data migrate crm schema-migration.json
polpo data migrate-sql crm sql-migration.json
polpo data migrations crm
polpo data rename crm customers --version 2
polpo data delete crm --version 2 --confirm crm

create accepts {name,schema}. execute accepts {operations,idempotencyKey?}. query accepts {sql,params?,mode?,maxRows?,idempotencyKey?}; the default mode is read and writes require "mode":"write". migrate is additive and accepts {expectedVersion,schema}. migrate-sql accepts {id,expectedVersion,statements:[{sql,params?}],allowDestructive?}. Schema administration requires manage access. Data uses the same selected project environment and the same Polpo key as the other runtime APIs. Commands default to Development; use --prod or --env production for Production. polpo deploy and polpo pull do not execute database migrations. For a self-hosted endpoint, set POLPO_API_KEY and pass --url http://localhost:3890/api. See Databases for SQL coverage, grants and request/result limits.

CLI

SDKs

Reference

Integrations

Templates

Resources

Command Reference

Cloud project setup

`polpo create`

`polpo link`

`polpo migrate`

`polpo install`

Authentication

Deployment

Custom tools

Runtime hooks

Active Run steering

Connections

Sandbox volumes

Agentic loops

BYOK

Projects and organizations

Cloud monitoring

Local runtime

Update

Application databases

​Cloud project setup

​polpo create

​polpo link

​polpo migrate

​polpo install

​Authentication

​Deployment

​Custom tools

​Runtime hooks

​Active Run steering

​Connections

​Sandbox volumes

​Agentic loops

​BYOK

​Projects and organizations

​Cloud monitoring

​Local runtime

​Update

​Application databases

Cloud project setup

`polpo create`

`polpo link`

`polpo migrate`

`polpo install`

Authentication

Deployment

Custom tools

Runtime hooks

Active Run steering

Connections

Sandbox volumes

Agentic loops

BYOK

Projects and organizations

Cloud monitoring

Local runtime

Update

Application databases