# VibePod CLI Commands Specification

**CLI Name:** `vp`  
**Framework:** Typer  

---

## Command Structure

```
vp
├── run <agent>           # Start agent container
├── stop <agent|--all>    # Stop containers
├── list                  # List agents
├── logs                  # View logs
│   ├── <agent>          # Container logs
│   ├── ui               # Open Datasette
│   ├── query            # SQL query
│   ├── export           # Export logs
│   └── stats            # Usage stats
├── exec <agent> <cmd>    # Execute in container
├── shell <agent>         # Open shell
├── skills                # AGENTS.lock commands
│   ├── init             # Initialize lockfile
│   ├── add              # Add skill
│   ├── sync             # Sync skills
│   ├── list             # List skills
│   └── mcp              # MCP server commands
├── config                # Configuration
│   ├── show             # Show config
│   ├── edit             # Edit config
│   ├── set              # Set value
│   └── path             # Show paths
├── auth                  # Authentication
│   ├── status           # Auth status
│   ├── login            # Login
│   └── logout           # Logout
├── init                  # Initialize project
├── update                # Update CLI/images
├── version               # Show version
└── help                  # Help
```

---

## Command Details

### `vp run`

Start an agent container.

```
vp run [AGENT] [OPTIONS]

Arguments:
  AGENT                   Agent to run (default: from config)
                         Choices: claude, gemini, opencode, devstral, auggie

Options:
  -w, --workspace PATH    Workspace directory (default: current dir)
  -p, --proxy            Enable API logging proxy
  -d, --detach           Run in background
  --port PORT            Override default port mappings
  -e, --env KEY=VAL      Set environment variable (can repeat)
  --prompt TEXT          Initial prompt to send
  --headless             Non-interactive mode (for CI)
  --pull                 Pull latest image before run
  --name TEXT            Custom container name
  --help                 Show help
```

**Behavior:**
1. Check Docker is running
2. Pull image if `--pull` or `auto_pull` config
3. Sync skills if `skills.auto_sync` enabled
4. Start container with:
   - Workspace mounted at `/workspace`
   - Config dir mounted at `/config`
   - Proxy if `--proxy`
   - Environment variables
5. Attach to container (unless `--detach`)

**Examples:**
```bash
vp run claude                     # Start Claude in current dir
vp run gemini -w ~/project        # Gemini with workspace
vp run opencode --proxy           # With API logging
vp run devstral -d                # Detached
vp run claude -e DEBUG=1          # With env var
vp run claude --headless --prompt "Fix tests"  # CI mode
```

---

### `vp stop`

Stop agent containers.

```
vp stop [AGENT] [OPTIONS]

Arguments:
  AGENT                   Agent to stop (optional)

Options:
  -a, --all              Stop all VibePod containers
  -f, --force            Force stop (SIGKILL)
  --help                 Show help
```

**Behavior:**
1. Find container(s) by name pattern `vibepod-{agent}-*`
2. Stop gracefully (SIGTERM)
3. If `--force`, use SIGKILL after timeout
4. Remove container if `auto_remove` config

**Examples:**
```bash
vp stop claude                    # Stop Claude
vp stop --all                     # Stop all
vp stop -af                       # Force stop all
```

---

### `vp list`

List available and running agents.

```
vp list [OPTIONS]

Options:
  -r, --running          Show only running containers
  -a, --available        Show only available agents
  --json                 Output as JSON
  --help                 Show help
```

**Output:**
```
AGENT      IMAGE                    STATUS      WORKSPACE
claude     vibepod/claude:latest    running     ~/project
gemini     vibepod/gemini:latest    stopped     -
opencode   vibepod/opencode:latest  not pulled  -
devstral   vibepod/devstral:latest  stopped     -
auggie     vibepod/auggie:latest    stopped     -
```

---

### `vp logs`

View and manage logs.

```
vp logs [SUBCOMMAND]

Subcommands:
  <agent>                View container logs
  ui                     Open Datasette UI
  query                  Run SQL query
  export                 Export logs
  stats                  Show usage statistics
  clear                  Clear log database
```

#### `vp logs <agent>`

```
vp logs <AGENT> [OPTIONS]

Options:
  -f, --follow           Follow log output
  -n, --tail INT         Number of lines (default: 100)
  --since TEXT           Show logs since (e.g., "1h", "2024-01-01")
  --help                 Show help
```

#### `vp logs ui`

```
vp logs ui [OPTIONS]

Options:
  --port INT             Port for Datasette (default: 8001)
  --no-open              Don't open browser
  --help                 Show help
```

**Behavior:**
1. Start `vibepod/datasette` container if not running
2. Mount `~/.config/vibepod/logs.db`
3. Open browser to `http://localhost:8001`

#### `vp logs query`

```
vp logs query <SQL> [OPTIONS]

Arguments:
  SQL                    SQL query to execute

Options:
  --format TEXT          Output format: table, json, csv (default: table)
  --help                 Show help
```

**Example:**
```bash
vp logs query "SELECT agent, COUNT(*) FROM requests GROUP BY agent"
```

#### `vp logs export`

```
vp logs export [OPTIONS]

Options:
  -o, --output PATH      Output file (default: stdout)
  --format TEXT          Format: csv, json (default: csv)
  --since TEXT           Export since date
  --agent TEXT           Filter by agent
  --help                 Show help
```

#### `vp logs stats`

```
vp logs stats [OPTIONS]

Options:
  --period TEXT          Period: day, week, month (default: week)
  --agent TEXT           Filter by agent
  --help                 Show help
```

**Output:**
```
API Usage (Last 7 Days)

AGENT      REQUESTS    TOKENS      COST
claude     142         523,401     $4.23
gemini     87          312,004     $1.56
opencode   23          89,234      $0.89
─────────────────────────────────────────
TOTAL      252         924,639     $6.68
```

---

### `vp exec`

Execute command in running container.

```
vp exec <AGENT> <COMMAND>... [OPTIONS]

Arguments:
  AGENT                   Agent container
  COMMAND                 Command to execute

Options:
  -i, --interactive      Interactive mode
  -t, --tty              Allocate TTY
  -w, --workdir PATH     Working directory
  --help                 Show help
```

**Examples:**
```bash
vp exec claude ls -la
vp exec gemini cat /workspace/README.md
vp exec opencode -it bash
```

---

### `vp shell`

Open shell in running container.

```
vp shell <AGENT> [OPTIONS]

Arguments:
  AGENT                   Agent container

Options:
  --shell TEXT           Shell to use (default: /bin/bash)
  --help                 Show help
```

**Equivalent to:** `vp exec <agent> -it /bin/bash`

---

### `vp skills`

Manage skills via AGENTS.lock.

```
vp skills [SUBCOMMAND]

Subcommands:
  init                   Initialize AGENTS.lock
  add                    Add a skill
  remove                 Remove a skill
  sync                   Sync skills to agents
  list                   List installed skills
  mcp                    Manage MCP servers
```

#### `vp skills init`

```
vp skills init [OPTIONS]

Options:
  --global               Initialize global lockfile
  --clients TEXT         Comma-separated clients (default: claude,gemini,codex)
  --help                 Show help
```

**Behavior:**
1. Create `AGENTS.lock` in current dir (or global)
2. Set default clients
3. Run `al init` under the hood

#### `vp skills add`

```
vp skills add <SOURCE> [OPTIONS]

Arguments:
  SOURCE                  Skill source (URL or shorthand)

Options:
  --group TEXT           Skill group
  --global               Add to global lockfile
  --help                 Show help
```

**Shorthand expansion:**
- `vibepod/testing` → `https://github.com/VibePod/skills/tree/main/testing`
- `anthropic/frontend-design` → `https://github.com/anthropics/skills/tree/main/skills/frontend-design`

**Examples:**
```bash
vp skills add vibepod/python-best-practices
vp skills add https://github.com/company/skills/tree/main/custom
vp skills add ./local-skill
vp skills add vibepod/testing --group dev
```

#### `vp skills sync`

```
vp skills sync [OPTIONS]

Options:
  --global               Sync global lockfile
  --group TEXT           Sync specific group only
  --help                 Show help
```

**Behavior:**
1. Read `AGENTS.lock`
2. Call `al sync`
3. Skills synced to appropriate agent config dirs

#### `vp skills list`

```
vp skills list [OPTIONS]

Options:
  --global               List global skills
  --json                 Output as JSON
  --help                 Show help
```

**Output:**
```
SKILL                         SOURCE                              GROUP
python-best-practices         VibePod/skills                      default
testing                       VibePod/skills                      dev
project-context               ./skills/project-context            default
```

#### `vp skills mcp`

```
vp skills mcp [SUBCOMMAND]

Subcommands:
  add                    Add MCP server
  remove                 Remove MCP server
  list                   List MCP servers
```

```bash
vp skills mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /workspace
vp skills mcp list
vp skills mcp remove filesystem
```

---

### `vp config`

Manage configuration.

```
vp config [SUBCOMMAND]

Subcommands:
  show                   Show configuration
  edit                   Edit in $EDITOR
  set                    Set a value
  get                    Get a value
  path                   Show config paths
  reset                  Reset to defaults
```

#### `vp config show`

```
vp config show [OPTIONS]

Options:
  --section TEXT         Show specific section
  --json                 Output as JSON
  --effective            Show merged global + project config
  --help                 Show help
```

#### `vp config set`

```
vp config set <KEY> <VALUE> [OPTIONS]

Arguments:
  KEY                    Config key (dot notation)
  VALUE                  Value to set

Options:
  --global               Set in global config
  --help                 Show help
```

**Examples:**
```bash
vp config set default_agent gemini
vp config set agents.claude.image vibepod/claude:1.0.0
vp config set logging.retention_days 60
```

#### `vp config path`

```
vp config path [OPTIONS]

Options:
  --global               Show global config path
  --project              Show project config path
  --help                 Show help
```

**Output:**
```
Global:  ~/.config/vibepod/config.yaml
Project: /home/user/myapp/.vibepod/config.yaml
Logs:    ~/.config/vibepod/logs.db
```

---

### `vp auth`

Manage agent authentication.

```
vp auth [SUBCOMMAND]

Subcommands:
  status                 Show auth status
  login                  Authenticate agent
  logout                 Remove credentials
```

#### `vp auth status`

```
vp auth status [OPTIONS]

Options:
  --agent TEXT           Specific agent
  --help                 Show help
```

**Output:**
```
AGENT      STATUS          EXPIRES
claude     authenticated   2026-03-01
gemini     authenticated   never (API key)
opencode   not configured  -
devstral   not configured  -
auggie     authenticated   2026-02-15
```

#### `vp auth login`

```
vp auth login <AGENT> [OPTIONS]

Arguments:
  AGENT                   Agent to authenticate

Options:
  --token TEXT           API token (or prompt)
  --help                 Show help
```

**Behavior:**
1. Start agent container with auth volume
2. Run agent's auth flow
3. Credentials stored in `~/.config/vibepod/agents/{agent}/`

---

### `vp init`

Initialize VibePod in a project.

```
vp init [OPTIONS]

Options:
  --agent TEXT           Default agent for project
  --no-skills            Skip AGENTS.lock creation
  --help                 Show help
```

**Creates:**
```
.vibepod/
└── config.yaml          # Project config

AGENTS.lock              # Skills lockfile (unless --no-skills)
```

---

### `vp update`

Update CLI and container images.

```
vp update [OPTIONS]

Options:
  --cli                  Update CLI only
  --images               Update images only
  --agent TEXT           Update specific agent image
  --help                 Show help
```

**Behavior:**
1. Check for new CLI version on PyPI
2. If `--cli` or no flags, offer to update CLI
3. If `--images` or no flags, pull latest images

---

### `vp version`

Show version information.

```
vp version [OPTIONS]

Options:
  --json                 Output as JSON
  --help                 Show help
```

**Output:**
```
VibePod CLI:    1.0.0
Python:         3.11.5
Docker:         24.0.7
AGENTS.lock:    0.1.0

Images:
  vibepod/claude:     latest (sha-abc123)
  vibepod/gemini:     latest (sha-def456)
  vibepod/opencode:   not pulled
  vibepod/devstral:   1.0.0
  vibepod/auggie:     latest (sha-ghi789)
```

---

## Aliases

Default aliases (configurable):

| Alias | Expands To |
|-------|------------|
| `vp c` | `vp run claude` |
| `vp g` | `vp run gemini` |
| `vp o` | `vp run opencode` |
| `vp d` | `vp run devstral` |
| `vp a` | `vp run auggie` |
| `vp ui` | `vp logs ui` |

Aliases are implemented via Typer's command aliasing or config-based dispatch.

---

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments |
| 3 | Docker not running |
| 4 | Image not found |
| 5 | Authentication required |
| 6 | Network error |
| 7 | Container error |
| 8 | Config error |

---

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `VP_CONFIG_DIR` | Config directory | `~/.config/vibepod` |
| `VP_DEFAULT_AGENT` | Default agent | `claude` |
| `VP_LOG_LEVEL` | Log level | `info` |
| `VP_NO_COLOR` | Disable colors | `false` |
| `DOCKER_HOST` | Docker socket | (system default) |
