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>] [-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>] [-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, memory, missions, playbooks, schedules, vault metadata, loop definitions, custom tools, and avatars when present.

polpo deploy [--dir <path>] [--yes] [--force] [--include-tasks] \
  [--include-runs] [--include-sessions] [--all]

--all enables the optional migration resources. --force overrides existing remote resources without prompting.

Custom tools

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

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

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

Connections

polpo connections list [--provider <provider>] [--status <status>] [--json]
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]

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>]
polpo byok list [--project <project-id>]
polpo byok remove <provider>

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>]
polpo cloud-logs [--follow] [--dir <path>]

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.

CLI

SDKs

Reference

Integrations

Templates

Resources

Command Reference

Cloud project setup

`polpo create`

`polpo link`

`polpo migrate`

`polpo install`

Authentication

Deployment

Custom tools

Connections

Sandbox volumes

Agentic loops

BYOK

Projects and organizations

Cloud monitoring

Local runtime

Update

​Cloud project setup

​polpo create

​polpo link

​polpo migrate

​polpo install

​Authentication

​Deployment

​Custom tools

​Connections

​Sandbox volumes

​Agentic loops

​BYOK

​Projects and organizations

​Cloud monitoring

​Local runtime

​Update

Cloud project setup

`polpo create`

`polpo link`

`polpo migrate`

`polpo install`

Authentication

Deployment

Custom tools

Connections

Sandbox volumes

Agentic loops

BYOK

Projects and organizations

Cloud monitoring

Local runtime

Update