CLI Reference¶

Complete reference for all vp commands, auto-generated from the source.

app¶

VibePod - One CLI for all AI coding agents

Usage:

vp [OPTIONS] COMMAND [ARGS]...

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:

vp a [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

agy¶

Alias for vp run agy.

Usage:

vp agy [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

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:

vp attach [OPTIONS] [CONTAINER]

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:

vp auggie [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

c¶

Alias for vp run claude.

Usage:

vp c [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

claude¶

Alias for vp run claude.

Usage:

vp claude [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

codex¶

Alias for vp run codex.

Usage:

vp codex [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

config¶

Manage configuration

Usage:

vp config [OPTIONS] COMMAND [ARGS]...

allow-dir¶

Add a directory to the vp run allow list.

Usage:

vp config allow-dir [OPTIONS] [DIRECTORY]

Options:

  [DIRECTORY]  Directory to allow (defaults to current directory)

init¶

Create a minimal project config or add a specific agent config.

Usage:

vp config init [OPTIONS] [AGENT]

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:

vp config list-allowed-dirs [OPTIONS]

path¶

Show config and logs paths.

Usage:

vp config path [OPTIONS]

Options:

  --global   Show global config path only
  --project  Show project config path only

remove-dir¶

Remove a directory from the vp run allow list.

Usage:

vp config remove-dir [OPTIONS] [DIRECTORY]

Options:

  [DIRECTORY]  Directory to remove (defaults to current directory)

show¶

Show effective merged config.

Usage:

vp config show [OPTIONS]

Options:

  --json  Output as JSON

copilot¶

Alias for vp run copilot.

Usage:

vp copilot [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

d¶

Alias for vp run devstral.

Usage:

vp d [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

devstral¶

Alias for vp run devstral.

Usage:

vp devstral [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

doctor¶

Inspect agent auth and config state

Usage:

vp doctor [OPTIONS] COMMAND [ARGS]...

claude¶

Inspect Claude Code credential state for diagnosing auth/refresh issues.

Usage:

vp doctor claude [OPTIONS]

g¶

Alias for vp run gemini.

Usage:

vp g [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

gemini¶

Alias for vp run gemini.

Usage:

vp gemini [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

list¶

List available agents and running containers.

Usage:

vp list [OPTIONS]

Options:

  -r, --running  Show only running agents
  --json         Output JSON

logs¶

View logs and traffic UI

Usage:

vp logs [OPTIONS] COMMAND [ARGS]...

start¶

Start or reuse Datasette for session and proxy logs.

Usage:

vp logs start [OPTIONS]

Options:

  --port INTEGER  Datasette host port
  --no-open       Do not open browser

status¶

Show Datasette container status.

Usage:

vp logs status [OPTIONS]

stop¶

Stop the Datasette container.

Usage:

vp logs stop [OPTIONS]

Options:

  -f, --force  Force stop

ui¶

Alias for vp logs start.

Usage:

vp logs ui [OPTIONS]

Options:

  --port INTEGER  Datasette host port
  --no-open       Do not open browser

n¶

Alias for vp run agy.

Usage:

vp n [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

o¶

Alias for vp run opencode.

Usage:

vp o [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

opencode¶

Alias for vp run opencode.

Usage:

vp opencode [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

p¶

Alias for vp run copilot.

Usage:

vp p [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

pi¶

Alias for vp run pi.

Usage:

vp pi [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

proxy¶

Manage the HTTP(S) proxy

Usage:

vp proxy [OPTIONS] COMMAND [ARGS]...

start¶

Start the proxy container.

Usage:

vp proxy start [OPTIONS]

status¶

Show proxy container status.

Usage:

vp proxy status [OPTIONS]

stop¶

Stop the proxy container.

Usage:

vp proxy stop [OPTIONS]

Options:

  -f, --force  Force stop

run¶

Start an agent container.

Usage:

vp run [OPTIONS] [AGENT]

Options:

  [AGENT]               Agent to run
  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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

skills¶

Manage VibePod skills

Usage:

vp skills [OPTIONS] COMMAND [ARGS]...

add¶

Install a skill from a locator.

Usage:

vp skills add [OPTIONS] LOCATOR

Options:

  LOCATOR       Skill locator (github:..., npm:..., ./path, ...)  [required]
  --id TEXT     Override the derived skill ID
  --scope TEXT  local|user (defaults to local inside a project, else user)
  --link        Symlink instead of copy (local sources only)
  --json        Emit JSON to stdout

delete¶

Remove an installed skill.

Usage:

vp skills delete [OPTIONS] SKILL_ID

Options:

  SKILL_ID      Skill ID to remove  [required]
  --scope TEXT  local|user
  --json

list¶

List installed skills across both scopes.

Usage:

vp skills list [OPTIONS]

Options:

  --scope TEXT  Filter by scope (local|user)
  --json

sync¶

Reconcile installed/ with the lockfile (no re-resolve).

Usage:

vp skills sync [OPTIONS]

Options:

  --scope TEXT  local|user
  --json

update¶

Re-resolve locators and rewrite the lockfile.

Usage:

vp skills update [OPTIONS] [SKILL_ID]

Options:

  [SKILL_ID]    Skill ID (omit to update all)
  --scope TEXT  local|user
  --json

stop¶

Stop an agent's containers, a specific container, or all managed containers.

Usage:

vp stop [OPTIONS] [TARGET]

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

task¶

Create and manage headless background agent tasks

Usage:

vp task [OPTIONS] COMMAND [ARGS]...

_watch-timeout¶

Internal helper launched by vp task create --timeout.

Usage:

vp task _watch-timeout [OPTIONS] TASK_ID TIMEOUT_SECONDS

Options:

  TASK_ID          Task id to enforce  [required]
  TIMEOUT_SECONDS  Timeout in seconds  [required]

cancel¶

Gracefully stop a running task while keeping its record and logs.

Usage:

vp task cancel [OPTIONS] TASK_ID

Options:

  TASK_ID  Task id (full or prefix)  [required]

create¶

Start an agent task in the background and print its id.

Usage:

vp task create [OPTIONS] AGENT PROMPT

Options:

  AGENT                 Agent to run headlessly  [required]
  PROMPT                Prompt to send to the agent  [required]
  -w, --workspace PATH  Workspace directory  [default: .]
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        Additional Docker network to connect the container to
  --timeout TEXT        Maximum task runtime before graceful stop. Use s/m/h
                        suffixes, or 'none' to opt out.  [default: 2h]
  --pull                Pull latest image before run
  --ikwid               I Know What I'm Doing: enable auto-approval flags for
                        supported agents

list¶

List recent tasks with container status.

Usage:

vp task list [OPTIONS]

Options:

  --agent TEXT     Filter by agent name
  --json           Output JSON
  --limit INTEGER  Max rows to show  [default: 20]

logs¶

Print the agent's stdout/stderr for a task.

Usage:

vp task logs [OPTIONS] TASK_ID

Options:

  TASK_ID       Task id (full or prefix)  [required]
  -f, --follow  Stream logs as they are written

rm¶

Remove one task, or all tasks with --all.

Usage:

vp task rm [OPTIONS] [TASK_ID]

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:

vp task run [OPTIONS] AGENT PROMPT

Options:

  AGENT                 Agent to run headlessly  [required]
  PROMPT                Prompt to send to the agent  [required]
  -w, --workspace PATH  Workspace directory  [default: .]
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        Additional Docker network to connect the container to
  --timeout TEXT        Maximum task runtime before graceful stop. Use s/m/h
                        suffixes, or 'none' to opt out.  [default: 2h]
  --pull                Pull latest image before run
  --ikwid               I Know What I'm Doing: enable auto-approval flags for
                        supported agents

status¶

Show container status and exit code for a task.

Usage:

vp task status [OPTIONS] TASK_ID

Options:

  TASK_ID  Task id (full or prefix)  [required]
  --json   Output JSON

ui¶

Alias for vp logs start.

Usage:

vp ui [OPTIONS]

version¶

Show version and runtime information.

Usage:

vp version [OPTIONS]

Options:

  --json  Output as JSON

x¶

Alias for vp run codex.

Usage:

vp x [OPTIONS]

Options:

  -w, --workspace PATH  Workspace directory  [default: .]
  --pull                Pull latest image before run
  -d, --detach          Run container in background
  -e, --env TEXT        Environment variable KEY=VALUE
  --name TEXT           Custom container name
  --network TEXT        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