> ## Documentation Index
> Fetch the complete documentation index at: https://beige.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> All beige commands, flags, and usage patterns

The `beige` CLI controls the gateway daemon, launches the TUI, and manages plugins.

```bash theme={null}
beige <command> [subcommand] [flags]
```

Running `beige` with no arguments prints help and exits.

***

## Gateway Commands

The gateway is the always-running process that manages sandboxes, routes tool calls, and enforces policies.

### `beige gateway start`

Start the gateway as a background daemon.

```bash theme={null}
beige gateway start
beige gateway start --foreground    # Run in foreground (stdout/stderr visible)
```

On first run, if `~/.beige/config.json5` does not exist, the gateway automatically runs setup before starting.

On startup, the gateway:

1. Loads and validates `config.json5`
2. Discovers installed plugins from `~/.beige/plugins/`
3. Loads plugins — calls `createPlugin()` and `register()` for each
4. Validates agent tool references against registered tools
5. Builds the sandbox Docker image if needed
6. Creates a Docker container for each configured agent
7. Starts socket servers and the HTTP API
8. Calls `plugin.start()` for each plugin (background processes)

### `beige gateway stop`

Stop the running gateway daemon.

```bash theme={null}
beige gateway stop
```

### `beige gateway restart`

Gracefully restart the gateway without losing state.

```bash theme={null}
beige gateway restart
```

The gateway drains in-flight calls, stops all plugins, tears down infrastructure, reloads config, and starts fresh. Use this after editing `config.json5`.

### `beige gateway status`

Check whether the gateway daemon is running.

```bash theme={null}
beige gateway status
```

### `beige gateway logs`

View the gateway log file.

```bash theme={null}
beige gateway logs           # Print full log and exit
beige gateway logs -f        # Follow (live tail)
```

***

## TUI Command

### `beige tui [agent]`

Launch the interactive TUI, connecting to the running gateway.

```bash theme={null}
beige tui                    # Connect using the first agent in config
beige tui assistant          # Connect as a specific agent
```

The gateway **must be running** before starting the TUI.

**Flags:**

| Flag              | Description                                    |
| ----------------- | ---------------------------------------------- |
| `[agent]`         | Agent name (defaults to first agent in config) |
| `--gateway`, `-g` | Gateway URL (default: `http://127.0.0.1:7433`) |
| `--config`, `-c`  | Config file path                               |

***

## Setup Command

### `beige setup`

Initialize `~/.beige/` with the default config.

```bash theme={null}
beige setup
```

Setup is idempotent — existing files are never overwritten.

***

## Plugin Commands

### `beige plugins install <source>`

Install plugins from a source.

```bash theme={null}
# From npm
beige plugins install npm:@scope/package
beige plugins install npm:@scope/package@1.2.3

# From GitHub
beige plugins install github:owner/repo
beige plugins install github:owner/repo/plugins/git
beige plugins install github:owner/repo#v1.2.0

# From local path
beige plugins install ./path/to/plugin

# Override conflicts
beige plugins install npm:@scope/package --force
```

The installer discovers plugins by scanning for `plugin.json` files. After installing, review your config.json5 to fill in any required values (like API keys), add the plugin's tools to your agent's `tools` array, and restart the gateway.

### `beige plugins list`

List all installed plugins.

```bash theme={null}
beige plugins list
```

### `beige plugins remove <name>`

Remove an installed plugin.

```bash theme={null}
beige plugins remove github
```

### `beige plugins update [name]`

Update a plugin or all plugins by re-fetching from the original install source.

```bash theme={null}
beige plugins update github    # Update one plugin
beige plugins update           # Update all installed plugins
```

***

## Global Flags

| Flag              | Description                                         |
| ----------------- | --------------------------------------------------- |
| `--config`, `-c`  | Config file path (default: `~/.beige/config.json5`) |
| `--gateway`, `-g` | Gateway URL for TUI commands                        |
| `--help`, `-h`    | Show help for the current command                   |

***

## Typical Workflow

```bash theme={null}
# First time
beige setup
export ANTHROPIC_API_KEY="sk-ant-..."

# Install plugins
beige plugins install npm:@matthias-hausberger/beige-toolkit

# Every time
beige gateway start                  # Shell 1: start gateway daemon
beige tui                            # Shell 2: interactive TUI

# After editing config
beige gateway restart                # Reload config without losing sessions

# Debugging
beige gateway logs -f                # Follow logs live
beige gateway status                 # Check if daemon is running
```