Appearance
pom CLI
pom drives the same workspaces, services and holders as the app, so a service started in a terminal shows up in the Services panel and the other way round. It ships inside the app at /Applications/Pomelo.app/Contents/MacOS/pom; add that folder to your PATH to run it in a terminal. pom help prints this list.
pom [-w <workspace>] [-c <pom.yml>] <command> [args]The workspace is the one the current directory is in, else the main one; -w picks another. A service is name or repo/name.
Services
| Command | What it does |
|---|---|
pom start <target> [--wait [--timeout 120s]] | Start a service, a repo's services, or a workspaces: group; --wait blocks until each is ready (its healthcheck, else its port): exit 0 ready, 2 timeout, 3 stopped |
pom stop [target] | Stop them; with no target, every service of the workspace |
pom restart <target> | Stop, then start |
pom status [-o json] | Services of the workspace and whether they run (json: up, ready, healthy) |
pom logs <service> [--since <mark>] [--raw] [-o json] | Recent output of a service, or only what it printed since a mark |
pom logs --mark <name> record where every service's output has got to | - |
pom mark <name> [-w b] one mark for a test step: log offsets and query counters | - |
pom queue wait-idle <service> [--timeout 60s] [-o json] | Wait until the service's Sidekiq/BullMQ queue (pom.yml queue:) has no work: exit 0 idle, 2 still busy |
pom queue counts <service> [-o json] | The queue's waiting, active, due and delayed jobs |
pom attach <service> | Attach this terminal to a running service (detach: close the terminal) |
pom ports | Every leased port |
pom url <service> | Where a service with a port listens, directly and through the dev proxy |
pom proxy fault add <service> [--path /x] [--status 503] [--delay 2s] [--rate 0.3] [--ttl 10m] | Make the dev proxy fail or slow down this workspace's requests to a service |
pom proxy fault ls [--all] [-o json] | rm <id> | clear | The fault rules in force; remove one, or every one of the workspace |
pom proxy | Serve the dev proxy and webhook relay for every project (pom start runs one in the background when neither the app nor another proxy does) |
pom run <name|"cmd"> [repo] | A command from the config (or any shell command) in the repo's worktree, with the workspace's env |
pom commands | The commands the config defines, per repo |
pom refresh | Stop every running service of the project (frees their ports) |
pom release [--disk] [--worktrees] [--yes] | Stop services and remove the shared containers; --disk also drops their volumes (database data), --worktrees deletes the branch workspaces |
Workspaces
| Command | What it does |
|---|---|
pom ws create <branch> [--repos a,b] [--env name] [--no-seed] [--fresh-db] [--from-stage n] | New workspace: worktrees, databases, env files, setup and seed; --fresh-db starts every database empty instead of copying main's |
pom ws delete <branch> [--from-stage n] | Stop it and remove its worktrees, databases and folder; the local branch goes too only when it is pushed or merged |
pom ws rename <branch> [name] | Set or clear the workspace's display name |
pom ws list | Workspaces, their repos and running services |
pom get workspaces [-o json] | Each workspace's readiness and phase |
pom describe workspace <branch> [-o json] | Its services, ports and repos missing from it |
pom apply [branch] [--yes] | Check out repos the config added but a workspace lacks |
pom prepare-main [--no-seed] | Reset main's databases, migrate and seed (new workspaces copy them) |
pom db create|drop|reset [branch] | The workspace's databases in the shared Postgres |
pom db clean [--dry-run] [--yes] | Drop this project's databases (and snapshots) no workspace uses |
pom db snapshot <name> [-w b] [--replace] [-o json] | Copy every database of the workspace into snapshot <name> |
pom db restore <name> [-w b] [--no-restart] [--main] [-o json] | Put the snapshot back: stops the workspace's services, restarts them after |
pom db snapshots [-w b] [-o json] | The workspace's snapshots and their sizes |
pom db snapshot drop <name> [-w b] | Drop a snapshot |
pom db baseline [-w b] [-o json] | Run the branch's migrations, then save ws__baseline again |
pom db mark <name> [-w b] | Save the workspace's query counters (pom mark saves logs too) |
pom db stats --since <mark> [--repeated n] [-w b] [-o json] | The queries the workspace ran since the mark: totals, slowest, repeated (N+1) |
pom db reseed [-w b] [--from main__baseline | --snapshot <name>] [--main] [-o json] | Replace the workspace's data, migrate, save ws__baseline; services restart |
Config
| Command | What it does |
|---|---|
pom config path | The config file in use |
pom config edit | Open it in $EDITOR, then check it still loads |
pom config explain [repo | repo/service] [--branch b] [--env name] [-o json] | What the config resolves to and where each value comes from |
pom config normalize [--dry-run] | Drop removed keys, migrate old tokens |
pom config export [--secrets] [-o file] | The config as YAML; --secrets seals the session's secrets with it into a bundle (password read from stdin) |
pom config import <file> [--config-only|--secrets-only] | Replace pom.yml with a YAML file or bundle (old one kept as pom.yml.bak) and store the bundle's secrets |
pom env ls <repo[/service]> [--branch b] [--env name] [--show-secrets] | - |
pom env get <repo[/service]> <KEY> | - |
pom env set <repo> KEY=VALUE... | - |
pom env unset <repo> KEY... | - |
pom doctor | What keeps the project from running, and how to fix it |
Projects and machine
| Command | What it does |
|---|---|
pom init [name] [--ai] | A new project from the git repo you are in (--ai: Claude finishes pom.yml) |
pom onboard [session] [--new name --repo path... [--branch b]] [--no-ai] | Claude writes a runnable pom.yml with you, in this terminal |
pom ps [--watch] | CPU and memory of every holder Pomelo started |
pom disk | Disk used by the registered projects |
pom modules [list|prune|clear] | The shared node_modules store: its copies, drop unused ones, or empty it |
pom mcp [--branch b] | MCP server on stdio for a coding agent working in this workspace |
Agents (one workspace at a time; --json for stable output)
| Command | What it does |
|---|---|
pom agent ls [workspace] [--all-workspaces] | The workspace's agent sessions: role, state, turn, holder |
pom agent start [workspace] [--role r] [--fresh] [--trust] [--prompt text | --prompt-file f] | [--system-prompt-file f] [--tools t] [--allowed-tools t] [--disallowed-tools t] [--permission-mode m] [--model m] [--extra-mcp-config f] start (or reuse) a session; --fresh starts role r on a new conversation; --trust says yes to the agent's prompt to trust the folder (else exit 7) |
pom agent read <workspace/role> [--turn n | --since n] [--full] | What the agent did in a turn (the last by default), from its transcript |
pom agent watch [workspace] [--from-start] [--timeout d] | Stream the workspace's agent events as NDJSON |
pom agent stop <workspace/role> | End a session |
pom agent send <workspace/role> <text | --file f> [--queue] [--take] | Submit one turn (refused unless idle; --queue waits, --take takes the session over) |
pom agent wait <workspace/role> [--until idle|awaiting_input|turn-end] [--turn n] [--timeout d] | Exit 0 reached, 2 timeout, 3 awaiting input, 4 died |
pom agent ask <workspace/role> <text | --file f> [--take] [--timeout d] | Send, wait for the turn to end, and read it |
pom agent interrupt <workspace/role> | Stop the current turn |
pom agent approve|deny <workspace/role> <request> [--always] | Answer a pending approval of the workspace policy |
pom agent takeover [workspace] --session-id <id> [--settings f] [--mcp-config f] | - |
pom agent release <workspace/role> | A person takes a session over, and hands it back |
pom completion bash|zsh|fish | - |
pom version | - |