CLI Reference¶
Complete reference for all vp commands, auto-generated from the source.
app¶
VibePod - One CLI for all AI coding agents
Usage:
Options:
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or
customize the installation.
a¶
Alias for vp run auggie.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
agy¶
Alias for vp run agy.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
attach¶
Reattach your terminal to a running VibePod-managed container.
Use this to rejoin an agent session after the terminal that started it
was closed. Find candidate containers with vp list.
Usage:
Options:
container Container name or ID to attach to (see `vp list`). Omit when
exactly one managed container is running.
auggie¶
Alias for vp run auggie.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
board¶
Work through vibepod-board projects with agents
Usage:
work¶
Claim planned tasks of a board project and let an agent implement each one.
Each task gets its own branch and worktree. The agent runs headless with the task as its prompt; after an optional --verify command passes, the task moves to Review with its branch. Failed and timed-out tasks go back to Planned (or blocked) with a note.
Usage:
Options:
project Board project key, such as VP [required]
-a, --agent <str> Agent that implements the tasks [required]
--board-url <str> Board URL; defaults to board.url or
VP_BOARD_URL
--name <str> Worker name on the board; defaults to
<agent>@<host>
--label <str> Only claim tasks with this label; repeat to
require more
--min-readiness <int range> Only claim tasks rated at least this ready
[1<=x<=10]
--task <str> Work on this one task, such as VP-12, then
exit
--once Work on one task, then exit
--max <int range> Exit after this many tasks [x>=1]
--poll <str> When no task is left, wait this long (30s, 5m)
and look again instead of exiting
--repo <path> Repository to work in; defaults to the task's
local path
--worktree-dir <path> Where task worktrees go; defaults to
<repo>-worktrees next to the repository
--base <str> Where new branches start; defaults to the
repository's current branch
--branch-template <str> Branch name from {issue}, {number}, {key} and
{project}; tasks without a GitHub issue use
{key}, such as vp-12 [default: issue-{issue}]
--existing <continue|refuse> When the task's branch or worktree exists:
continue or refuse [default: continue]
--keep-worktree Keep worktrees after the hand-over
--profile <str> Credential profile to use (see `vp profile
list`)
--provider <str> Temporary model provider(s) for the agent runs
--ikwid Enable the agent's auto-approval flags
--timeout <str> Time limit per task (s/m/h), or 'none'
[default: 2h]
-e, --env <str> Environment variable KEY=VALUE for the agent
--network <str> Additional Docker network for the agent
container
--no-overlay Skip the project overlay image
--verify <str> Command that must pass in the worktree before
the hand-over
--on-fail <planned|blocked> Where failed and timed-out tasks go: planned
(counts an attempt) or blocked [default:
planned]
--max-attempts <int range> Failed attempts before a task is blocked
[x>=1]
--parallel Run alongside other workers on the same
profile
--usage-limit-wait <str> Pause after a usage limit when the agent names
no reset time [default: 30m]
c¶
Alias for vp run claude.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
claude¶
Alias for vp run claude.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
codex¶
Alias for vp run codex.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
config¶
Manage configuration
Usage:
allow-dir¶
Add a directory to the vp run allow list.
Usage:
Options:
init¶
Create a minimal project config or add a specific agent config.
Usage:
Options:
agent Optional agent config to copy into project
--force Overwrite existing project config if present
list-allowed-dirs¶
List all directories in the vp run allow list.
Usage:
path¶
Show configuration, logs, and proxy database paths.
Usage:
Options:
remove-dir¶
Remove a directory from the vp run allow list.
Usage:
Options:
show¶
Show effective merged config.
Usage:
Options:
copilot¶
Alias for vp run copilot.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
d¶
Alias for vp run vibe.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
devstral¶
Alias for vp run vibe.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
doctor¶
Inspect agent auth and config state
Usage:
claude¶
Inspect Claude Code credential state for diagnosing auth/refresh issues.
Usage:
Options:
herdr¶
Diagnose herdr terminal-multiplexer wiring end to end.
Run this INSIDE a herdr pane. Without an agent: passive summary of every agent's integration state. With an agent: checks pane env, socket, binary, the injected integration files, the hook trace log, performs a live host-side state report, and (when Docker is available) reproduces the exact in-container herdr call.
Usage:
Options:
agent Agent to inspect in depth; omit for an all-agents summary
--profile <str> Credential profile to inspect (see `vp profile list`)
ds¶
Alias for vp run dsh.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
dsh¶
Alias for vp run dsh.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
fb¶
Alias for vp run freebuff.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
freebuff¶
Alias for vp run freebuff.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
g¶
Alias for vp run gemini.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
gemini¶
Alias for vp run gemini.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
h¶
Alias for vp run hermes.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
hermes¶
Alias for vp run hermes.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
j¶
Alias for vp run jcode.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
jcode¶
Alias for vp run jcode.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
list¶
List available agents and running containers.
Usage:
Options:
logs¶
View logs and traffic UI
Usage:
start¶
Start or reuse Datasette for session and proxy logs.
Usage:
Options:
status¶
Show Datasette container status.
Usage:
stop¶
Stop the Datasette container.
Usage:
Options:
ui¶
Alias for vp logs start.
Usage:
Options:
n¶
Alias for vp run agy.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
o¶
Alias for vp run opencode.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
opencode¶
Alias for vp run opencode.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
p¶
Alias for vp run copilot.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
pi¶
Alias for vp run pi.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
profile¶
Manage credential profiles (separate agent logins per environment)
Usage:
create¶
Create a new empty profile.
Usage:
Options:
list¶
List profiles, the active one, and which agents have stored data.
Usage:
remove¶
Remove a profile and its stored credentials.
Usage:
Options:
provider¶
Manage global model providers
Usage:
add¶
Configure an endpoint, credentials, and selected models interactively.
Usage:
edit¶
Edit settings and optionally refresh/select models, without exposing saved keys.
Usage:
Options:
export¶
Write a shareable provider file; stored credentials are never included.
Usage:
Options:
import¶
Create a provider from a shared file. Keys are asked for, never read from the file.
Usage:
Options:
source Local file path or http(s) URL [required]
--name <str> Store under this name instead of the file's
--key-env <str> Read the API key from this environment variable
list¶
List provider identities without reading credentials.
Usage:
models¶
Show cached model IDs, optionally querying the server again.
Usage:
Options:
refresh¶
Re-discover models, choose which to use, and set the default; nothing else changes.
Usage:
Options:
remove¶
Remove a global provider, including its stored key.
Usage:
Options:
proxy¶
Manage the HTTP(S) proxy
Usage:
filter¶
Manage proxy allow/deny filtering
Usage:
allow¶
Manage the allow list
Usage:
# add¶
Add a host pattern to the allow list.
Usage:
Options:
host Host pattern [required]
--profile <str> Profile whose filter to manage (default: the active
profile)
# remove¶
Remove a host pattern from the allow list.
Usage:
Options:
host Host pattern [required]
--profile <str> Profile whose filter to manage (default: the active
profile)
deny¶
Manage the deny list
Usage:
# add¶
Add a host pattern to the deny list.
Usage:
Options:
host Host pattern [required]
--profile <str> Profile whose filter to manage (default: the active
profile)
# remove¶
Remove a host pattern from the deny list.
Usage:
Options:
host Host pattern [required]
--profile <str> Profile whose filter to manage (default: the active
profile)
mode¶
Set the filter mode (open = no filtering).
Usage:
Options:
value open, allow, or deny [required]
--profile <str> Profile whose filter to manage (default: the active
profile)
status¶
Show filter mode, lists, and proxy state.
Usage:
Options:
start¶
Start the proxy container.
Usage:
status¶
Show proxy container status.
Usage:
stop¶
Stop the proxy container.
Usage:
Options:
q¶
Alias for vp run qwen.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
qwen¶
Alias for vp run qwen.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
run¶
Start an agent container.
Usage:
Options:
agent Agent to run
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
skills¶
Manage VibePod skills
Usage:
add¶
Install a skill from a locator.
Usage:
Options:
locator Skill locator (github:..., npm:..., ./path, ...) [required]
--id <str> Override the derived skill ID
--scope <str> local|user (defaults to local inside a project, else user)
--link Symlink instead of copy (local sources only)
--json Emit JSON to stdout
cache¶
Manage the skills source cache
Usage:
clear¶
Remove cached git clones and npm packages (installed skills are kept).
Usage:
Options:
delete¶
Remove an installed skill.
Usage:
Options:
export¶
Copy installed skills as plain folders to
Usage:
Options:
skill_ids... Skill IDs to export [required]
--path <path> Directory to copy the skill folders into (default: .)
--scope <str> local|user (default: both, local shadows user)
--force Replace skill folders that already exist in the path
--json Emit JSON to stdout
list¶
List installed skills across both scopes.
Usage:
Options:
sync¶
Reconcile installed/ with the lockfile (no re-resolve).
Usage:
Options:
update¶
Re-resolve locators and rewrite the lockfile.
Usage:
Options:
stop¶
Stop an agent's containers, a specific container, or all managed containers.
Usage:
Options:
target Agent name/shortcut (stops all its containers) or a container
name or ID from `vp list` (stops just that container).
-a, --all Stop all VibePod managed containers
-f, --force Force stop
t¶
Alias for vp run tau.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
task¶
Create and manage headless background agent tasks
Usage:
_watch-timeout¶
Internal helper launched by vp task create --timeout.
Usage:
Options:
cancel¶
Gracefully stop a running task while keeping its record and logs.
Usage:
Options:
create¶
Start an agent task in the background and print its id.
Usage:
Options:
agent Agent to run headlessly [required]
prompt Prompt to send to the agent [required]
-w, --workspace <path> Workspace directory [default: .]
-e, --env <str> Environment variable KEY=VALUE
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--timeout <str> Maximum task runtime before graceful stop. Use s/m/h
suffixes, or 'none' to opt out. [default: 2h]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
--ikwid I Know What I'm Doing: enable auto-approval flags
for supported agents
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporary model provider(s) for this launch (see `vp
provider list`)
list¶
List recent tasks with container status.
Usage:
Options:
logs¶
Print the agent's stdout/stderr for a task.
Usage:
Options:
rm¶
Remove one task, or all tasks with --all.
Usage:
Options:
task_id Task id (full or prefix); omit when using --all
--all Remove all task records and their containers
-f, --force Kill a running container before removing
run¶
Deprecated alias for task create.
Usage:
Options:
agent Agent to run headlessly [required]
prompt Prompt to send to the agent [required]
-w, --workspace <path> Workspace directory [default: .]
-e, --env <str> Environment variable KEY=VALUE
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--timeout <str> Maximum task runtime before graceful stop. Use s/m/h
suffixes, or 'none' to opt out. [default: 2h]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
--ikwid I Know What I'm Doing: enable auto-approval flags
for supported agents
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporary model provider(s) for this launch (see `vp
provider list`)
status¶
Show container status and exit code for a task.
Usage:
Options:
tau¶
Alias for vp run tau.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
ui¶
Alias for vp logs start.
Usage:
version¶
Show version and runtime information.
Usage:
Options:
vibe¶
Alias for vp run vibe.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider
x¶
Alias for vp run codex.
Usage:
Options:
-w, --workspace <path> Workspace directory [default: .]
--pull Pull latest image before run
--no-overlay Skip the project overlay image
--rebuild-overlay Force rebuilding the project overlay image
--no-herdr Skip herdr terminal-multiplexer wiring
-d, --detach Run container in background
-e, --env <str> Environment variable KEY=VALUE
-p, --publish <str> Publish a container port in `docker run -p` syntax
(e.g. 127.0.0.1:3090:3081); replaces configured
agents.<agent>.ports for this run
-v, --volume <str> Mount a host path or named volume as
SOURCE:TARGET[:ro|rw]; added to configured
agents.<agent>.volumes (same TARGET replaces)
--name <str> Custom container name
--network <str> Additional Docker network to connect the container
to
--paste-images Enable image pasting via X11 clipboard (requires
DISPLAY to be set)
--ikwid I Know What I'm Doing: enable auto-approval / skip
permission prompts
--acp Run as an Agent Client Protocol (ACP) adapter for
ACP-capable editors
--profile <str> Credential profile to use (see `vp profile list`)
--provider <str> Temporarily use a global provider