> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Reference

> Polpo CLI 0.15.35 command reference

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

## Cloud project setup

### `polpo create`

```bash theme={null}
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/polpo.json`, and creates local environment configuration.

```bash theme={null}
polpo link --project-id <uuid> [-d, --dir <path>] [--api-url <url>] [-y, --yes]
```

### `polpo install`

```bash theme={null}
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

```bash theme={null}
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.

```bash theme={null}
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(...)`.

```bash theme={null}
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.

## Agentic loops

```bash theme={null}
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

```bash theme={null}
polpo byok set <provider> [--key <key>] [--label <label>] [--project <project-id>]
polpo byok list [--project <project-id>]
polpo byok remove <provider>
```

## Projects and organizations

```bash theme={null}
polpo projects list [--org <org-id>]
polpo projects create <name> [--org <org-id>]
polpo orgs list [--json]
```

## Cloud monitoring

```bash theme={null}
polpo cloud-status [--dir <path>]
polpo cloud-logs [--follow] [--dir <path>]
```

## Local runtime

The OSS CLI also exposes local project operations:

| Command                                                     | Purpose                               |
| ----------------------------------------------------------- | ------------------------------------- |
| `polpo init`                                                | 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

```bash theme={null}
polpo update [--check]
polpo upgrade [--check]
```

`update` and `upgrade` are aliases.