CLI Reference

All beige commands, flags, and usage patterns

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

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.

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.

beige gateway stop

beige gateway restart

Gracefully restart the gateway without losing state.

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.

beige gateway status

beige gateway logs

View the gateway log file.

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.

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.

beige setup

Setup is idempotent — existing files are never overwritten.

---

Plugin Commands

beige plugins install <source>

Install plugins from a source.

# 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.

beige plugins list

beige plugins remove <name>

Remove an installed plugin.

beige plugins remove github

beige plugins update [name]

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

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

# 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