---
description: Complete reference for vibepit commands, flags, and arguments including run, up, down, connect, exec, status, allow-http, allow-dns, monitor, update, and self-update.
---

# CLI Reference

`vibepit` is a single binary that manages sandbox sessions, network filtering,
and runtime administration. When you run `vibepit` without a subcommand, it
defaults to the [`run`](#run) command.

```
vibepit [global-flags] [command] [command-flags] [arguments]
```

## Global flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--debug` | bool | `false` | Enable debug output |

---

## `run`

Start a new sandbox session or attach to an existing one.

```
vibepit run [flags] [project-path]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `project-path` | Path to the project directory. Defaults to the current working directory. |

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `-L`, `--local` | bool | `false` | Use the local `vibepit:latest` image instead of the published one. Required when you [build a custom image](../how-to/troubleshooting.md#sandbox-image-not-found) for an unsupported UID/GID combination. |
| `-a`, `--allow` | string (repeatable) | | Additional `domain:port` entries to allow through the proxy (e.g. `api.example.com:443`) |
| `-p`, `--preset` | string (repeatable) | | Additional network presets to activate |
| `-r`, `--reconfigure` | bool | `false` | Re-run the network preset selector |

### Behavior

- If `project-path` is omitted, `vibepit` uses the current working directory.
- If the directory is inside a Git repository, `vibepit` resolves to the
  repository root and uses that as the project directory.
- `vibepit` refuses to run if the resolved project directory is your home
  directory.
- If a session is already running for the same project directory, `vibepit`
  attaches to it instead of starting a new one.
- On first run in a project, `vibepit` launches an interactive setup flow to
  select network presets. Pass `--reconfigure` to re-run this selector later.
- Entries passed with `--allow` and `--preset` are merged with any entries
  saved in the project configuration file.

### Examples

```bash
# Start a session in the current directory
vibepit

# Start a session for a specific project
vibepit run ~/projects/my-app

# Use a locally built image
vibepit run -L

# Allow access to an additional domain
vibepit run -a api.example.com:443

# Allow multiple domains and enable a preset
vibepit run -a api.example.com:443 -a cdn.example.com:443 -p vcs-github

# Re-run the network preset selector
vibepit run -r
```

---

## `up`

Start a sandbox session in daemon mode. The sandbox and proxy containers run in
the background with an SSH server, and `vibepit` returns immediately after the
session is ready.

```
vibepit up [flags] [project-path]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `project-path` | Path to the project directory. Defaults to the current working directory. |

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `-L`, `--local` | bool | `false` | Use the local `vibepit:latest` image instead of the published one. |
| `-a`, `--allow` | string (repeatable) | | Additional `domain:port` entries to allow through the proxy (e.g. `api.example.com:443`) |
| `-p`, `--preset` | string (repeatable) | | Additional network presets to activate |
| `-r`, `--reconfigure` | bool | `false` | Re-run the network preset selector |

### Behavior

- Creates an isolated network, proxy container, and sandbox container, the same
  as [`run`](#run).
- Generates ephemeral SSH keypairs (one for the client, one for the host)
  and stores them in `$XDG_STATE_HOME/vibepit/sessions/<sessionID>/`.
- The sandbox container runs an SSH server on port 2222 (internal). The port is
  forwarded through the proxy container and published to `127.0.0.1` on a random
  host port.
- Waits for the SSH daemon to accept connections before returning.
- If a session is already running for the same project directory, prints a
  message and exits without starting a new one.
- If orphaned containers from a previous session are detected, exits with an
  error asking you to run `vibepit down` first.

### Examples

```bash
# Start a daemon-mode session in the current directory
vibepit up

# Start with a network preset
vibepit up -p vcs-github

# Start for a specific project
vibepit up ~/projects/my-app
```

---

## `down`

Stop and remove sandbox and proxy containers for a session.

```
vibepit down [project-path]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `project-path` | Path to the project directory. Defaults to the current working directory. |

### Behavior

- Finds the running session for the project directory.
- Stops and removes all containers belonging to the session (sandbox and proxy).
- Removes the session network.
- Deletes session credentials (mTLS and SSH keys) from
  `$XDG_STATE_HOME/vibepit/sessions/<sessionID>/`.
- If some containers cannot be removed, credentials are preserved so you can
  retry.
- Also detects orphaned containers (e.g., proxy still running after sandbox
  crashed) and cleans them up.

### Examples

```bash
# Stop the session for the current directory
vibepit down

# Stop the session for a specific project
vibepit down ~/projects/my-app
```

---

## `connect`

Aliases: `c`

Connect to a running sandbox.

```
vibepit connect
```

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `-b`, `--bar` | bool | `false` | Enable status bar [EXPERIMENTAL] |

### Behavior

- Resolves the project root from the current working directory and finds the
  running session.
- Loads the SSH client key from the session credentials directory.
- Connects to `127.0.0.1` on the published SSH port with public key
  authentication.
- Requests a PTY, starts a shell, and forwards terminal resize events
  (`SIGWINCH`).
- When detached sessions exist inside the sandbox, the SSH server presents a
  session selector. You can reattach to a previous session or start a new one.

### Examples

```bash
# Open an interactive shell
vibepit connect
```

---

## `exec`

Execute a command in the sandbox.

```
vibepit exec <command...>
```

### Arguments

| Argument | Description |
|----------|-------------|
| `command...` | The remote command to execute. |

### Behavior

- Resolves the project root from the current working directory and finds the
  running session.
- Loads the SSH client key from the session credentials directory.
- Connects to `127.0.0.1` on the published SSH port with public key
  authentication.
- Executes the command on the remote side and returns its exit code. Stdin,
  stdout, and stderr are forwarded.

### Examples

```bash
# Run a single command
vibepit exec ls -la

# Run a command that reads a file
vibepit exec cat /etc/os-release
```

---

## `status`

Show session status.

```
vibepit status [project-path]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `project-path` | Path to the project directory. Defaults to the current working directory. |

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `-v`, `--verbose` | bool | `false` | Enable verbose output |

### Output

When run inside a project directory (or given a project path), displays the
session status for that project. When no session is found for the current
project, or when run outside a project directory, displays status for all
running sessions on the machine.

Example output:

```
  Session   cq1abc2def3gh4ij
  Project   /home/user/my-project
  Sandbox   running: vibepit-sandbox-cq1abc2def3gh4ij (up 2m30s)
    Proxy   running: vibepit-proxy-cq1abc2def3gh4ij (up 2m31s)
      API   127.0.0.1:41923
      SSH   127.0.0.1:52847
```

If no sessions are running at all, prints `No active session for <path>` (when
in a project) or `No active sessions` (when outside a project).

---

## `allow-http`

Add HTTP(S) allowlist entries for a running session. By default, entries are
also persisted to the project configuration file so they apply on future runs.

```
vibepit allow-http [flags] <domain:port-pattern>...
```

### Arguments

| Argument | Description |
|----------|-------------|
| `domain:port-pattern` | One or more domain-and-port patterns to allow. Required. The port is not optional — use `example.com:443` for HTTPS, `example.com:80` for HTTP, or `example.com:*` for any port. |

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--no-save` | bool | `false` | Skip persisting the entries to the project config |
| `--session` | string | | Session ID or project path (skips interactive selection) |

### Wildcard semantics

`*` matches exactly one DNS label. `**` matches one or more labels. Both can
appear in any position but at most one `**` per pattern.

| Pattern | Matches | Does not match |
|---|---|---|
| `*.example.com:443` | `api.example.com` | `example.com`, `a.b.example.com` |
| `**.example.com:443` | `api.example.com`, `a.b.example.com` | `example.com` |
| `bedrock.*.amazonaws.com:443` | `bedrock.us-east-1.amazonaws.com` | `bedrock.a.b.amazonaws.com` |

Ports must be an exact number or `*` for any port.

### Examples

```bash
# Allow a single domain
vibepit allow-http api.example.com:443

# Allow all subdomains (one level) of a domain
vibepit allow-http '*.example.com:443'

# Allow multiple entries without saving to config
vibepit allow-http --no-save api.example.com:443 cdn.example.com:443

# Target a specific session
vibepit allow-http --session my-session-id api.example.com:443
```

---

## `allow-dns`

Add DNS allowlist entries for a running session. By default, entries are also
persisted to the project configuration file so they apply on future runs.

```
vibepit allow-dns [flags] <domain-pattern>...
```

### Arguments

| Argument | Description |
|----------|-------------|
| `domain-pattern` | One or more domain patterns to allow DNS resolution for. Required. |

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--no-save` | bool | `false` | Skip persisting the entries to the project config |
| `--session` | string | | Session ID or project path (skips interactive selection) |

### Wildcard semantics

`*` matches exactly one DNS label. `**` matches one or more labels. Both can
appear in any position but at most one `**` per pattern.

| Pattern | Matches | Does not match |
|---|---|---|
| `*.example.com` | `api.example.com` | `example.com`, `a.b.example.com` |
| `**.example.com` | `api.example.com`, `a.b.example.com` | `example.com` |

### Examples

```bash
# Allow DNS resolution for a domain
vibepit allow-dns example.com

# Allow DNS resolution for all subdomains
vibepit allow-dns '*.example.com'

# Allow without saving to config
vibepit allow-dns --no-save example.com
```

---

## `monitor`

Aliases: `m`, `tv`

Open an interactive terminal UI for viewing proxy logs and performing admin
actions on a running session.

```
vibepit monitor [flags]
```

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--session` | string | | Session ID or project path (skips interactive selection) |

### Behavior

- If `--session` is not provided and multiple sessions are running,
  `vibepit` presents an interactive session selector.
- If only one session is running, `vibepit` connects to it directly.

---

## `update`

Update the vibepit binary and pull the latest container images.

```
vibepit update [flags]
```

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--bin` | bool | `false` | Update the binary only (skip image pull) |
| `--images` | bool | `false` | Update container images only (skip binary update) |
| `--check` | bool | `false` | Check for available updates without installing |
| `--list` | bool | `false` | List available releases |
| `--use` | string | | Install a specific version (implies `--bin`) |
| `--pre` | bool | `false` | Use the prerelease channel |
| `-y`, `--yes` | bool | `false` | Skip the confirmation prompt |

### Behavior

By default, `vibepit update` updates both the binary and the container images.
Use `--bin` or `--images` to update only one. The two flags are mutually
exclusive.

**Binary update:**

- Checks the release channel for a newer version and downloads it.
- Verifies the download with SHA-256 checksums and cosign signature bundles
  (when available).
- Replaces the running binary in place.
- If vibepit was installed via a package manager (Homebrew, Snap, Nix, etc.),
  the binary update is skipped with a message to use the package manager instead.
- Use `--use <version>` to install a specific version regardless of what the
  channel reports as latest.
- Use `--pre` to check the prerelease channel instead of the stable channel.

**Image update:**

- Pulls the latest sandbox image for your UID/GID combination (e.g.,
  `ghcr.io/bernd/vibepit:r1-uid-1000-gid-1000`).
- Pulls the latest proxy base image.

### Examples

```bash
# Update everything (binary + images)
vibepit update

# Check if an update is available
vibepit update --check

# List available releases
vibepit update --list

# Update binary only, skip confirmation
vibepit update --bin -y

# Update images only
vibepit update --images

# Install a specific version
vibepit update --use 0.2.0

# Check the prerelease channel
vibepit update --check --pre
```

