Version: 5.0.0

# Command Line Interface

Visibox ships with a `visibox` command-line tool for controlling a running Visibox instance from your shell. It’s a lightweight alternative to the [AI Assistants](https://manual.spaceage.tv/5.0.0/integrations/ai/) integration for quick one-offs, shell aliases, scripting, and hotkey tools.

The CLI is a thin wrapper over the same [HTTP REST API](https://manual.spaceage.tv/5.0.0/integrations/api/) used by the Stream Deck plugin and the MCP server — so anything the CLI can do, any other client can too.

## Installation

Install the CLI from inside Visibox:

1.  Choose **Settings > Install CLI Tool…** (on Mac, from the Visibox menu; on Windows, from the File menu).
2.  Visibox installs the command and shows you where it landed. Open a new terminal and run `visibox health` (Mac, or Windows from Command Prompt or PowerShell) or `visibox.cmd health` (Windows from Git Bash or WSL) to confirm it’s working.

To remove it later, choose **Settings > Install CLI Tool…** again — Visibox will detect that it’s already installed and offer an **Uninstall** option.

### Where it lands

| Platform | Install path | Invoke as |
| --- | --- | --- |
| macOS | `/usr/local/bin/visibox` | `visibox` |
| Windows | `%LOCALAPPDATA%\Visibox\bin\visibox.cmd` | `visibox` or `visibox.cmd` |

On macOS, `/usr/local/bin` is already on your `$PATH`, so `visibox` works in any shell.

On Windows, Visibox adds `%LOCALAPPDATA%\Visibox\bin` to your user PATH. In **Command Prompt** and **PowerShell**, you can type `visibox` and Windows resolves it to `visibox.cmd` automatically (via `PATHEXT`). In **Git Bash**, **WSL**, or other Unix-style shells on Windows, type `visibox.cmd` explicitly — those shells don’t apply `PATHEXT`. To shorten it in bash, add `alias visibox=visibox.cmd` to your `~/.bashrc`.

note

You may need to open a new terminal window (or `source` your shell profile) after installing so the command is on your `PATH`.

## Quick Start

```
# Is Visibox running?visibox health# What's playing?visibox status# Control playbackvisibox playvisibox stopvisibox nextvisibox prev
```

## Connection and Authentication

By default the CLI connects to `http://127.0.0.1:51736` on your local machine, and localhost connections skip authentication — nothing to configure for scripting your own Visibox.

For connecting to a remote Visibox, you need a pairing token. See [Remote Pairing](https://manual.spaceage.tv/5.0.0/integrations/remote-pairing/) for how to pair, then pass the token via a flag or environment variable:

| Flag / Variable | Purpose |
| --- | --- |
| `--host <host>` / `VISIBOX_HOST` | Host to connect to |
| `--port <port>` / `VISIBOX_PORT` | Port (default `51736`) |
| `--token <token>` / `VISIBOX_TOKEN` | Pairing token for remote connections |

The CLI also reads a token from `~/.visibox/mcp-token` if present — the same file the MCP server uses — so if MCP is already working, the CLI works too.

## Playback

| Command | What it does |
| --- | --- |
| `visibox play` | Start playback |
| `visibox stop` | Stop playback |
| `visibox pause` | Pause |
| `visibox resume` | Resume |
| `visibox next` | Next Clip |
| `visibox prev` | Previous Clip |
| `visibox next-song` | Next Song |
| `visibox prev-song` | Previous Song |
| `visibox restart` | Restart the current Clip |
| `visibox stop-all` | Stop all playing Clips |
| `visibox play-toggle` | Toggle play/stop |
| `visibox pause-toggle` | Toggle pause/resume |
| `visibox play-clip <index>` | Play the Clip at the given index (0-based) |
| `visibox song <index|id>` | Switch to a Song by index or ID |
| `visibox trigger <clipId>` | Trigger a specific Clip |
| `visibox seek <clipId> <percent>` | Seek within a Clip (0–100) |

## System

| Command | What it does |
| --- | --- |
| `visibox fullscreen` | Toggle the Output Window fullscreen |
| `visibox mute` | Toggle output mute |
| `visibox volume <0-100>` | Set master output volume |
| `visibox panic` | Emergency reload — restart all Visibox windows |

## Query

| Command | What it returns |
| --- | --- |
| `visibox projects` | All open projects |
| `visibox project [id]` | Detail for a project (defaults to the active one) |
| `visibox songs` | Songs in the active Project |
| `visibox clips <songId>` | Clips in a specific Song |
| `visibox presets` | Available Visualizer and Effect presets |
| `visibox cameras` | Connected cameras and HDMI video inputs |
| `visibox app-state` | Fullscreen / mute / volume state |

## Editing

The CLI exposes a single `edit` command that dispatches to any edit action supported by the API:

```
visibox edit song:update-title --param songId=abc123 --param title="New Title"visibox edit clip:delete --param clipId=xyz789
```

The action names and parameters match the [WebSocket action schema](https://manual.spaceage.tv/5.0.0/integrations/api/#sending-actions). This is the same mechanism the AI Assistants integration uses under the hood.

## JSON Output

Append `--json` to any command to get machine-readable output instead of formatted text. This is the right mode for piping into `jq`, `grep`, or another script:

```
visibox status --json | jq '.project.name'visibox songs --json | jq -r '.[].title'
```

## Targeting a Specific Project

Most commands default to the active Project. Use `--project <id>` to target a different one:

```
visibox songs --project abc123visibox play --project abc123
```

## Global Options

| Option | Description |
| --- | --- |
| `--json` | Output raw JSON instead of formatted text |
| `--host <host>` | Visibox host (default `127.0.0.1`) |
| `--port <port>` | Visibox port (default `51736`) |
| `--token <token>` | Auth token for remote connections |
| `--project <id>` | Target Project ID (default: active Project) |
| `--timeout <ms>` | Request timeout in milliseconds (default `5000`) |

## Exit Codes

| Code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | Application error (Visibox returned an error) |
| `2` | Connection error (Visibox not running or unreachable) |

Exit codes make the CLI friendly to shell scripts — check `$?` or chain with `&&` / `\|\|` like any other Unix tool.

## Examples

The examples below are written for bash (macOS, Linux, WSL, Git Bash). On Windows, run them from Git Bash or WSL, or translate the loops and `jq` pipelines to PowerShell. In Git Bash, substitute `visibox.cmd` for `visibox`.

```
# Fire off a panic reload from a Stream Deck button, keyboard shortcut tool, or hotkey appvisibox panic# Rotate through songs on a timer (e.g., in a soundcheck playlist script)for i in 1 2 3 4 5; do  visibox song $i  sleep 30done# Dump a set list for a show documentvisibox songs --json | jq -r '.[] | "\(.index). \(.title)"'# Trigger the first Clip of every Song in sequence — hands-off previewvisibox songs --json | jq -r '.[].id' | while read songId; do  visibox song "$songId"  visibox play-clip 0  sleep 15done
```

tip

The CLI, the [Stream Deck plugin](https://manual.spaceage.tv/5.0.0/stream-deck/), and [AI Assistants](https://manual.spaceage.tv/5.0.0/integrations/ai/) are three ways to reach the same underlying API. Reach for the CLI when you want scripting or shell-speed control, the Stream Deck for physical buttons, and an AI assistant when you want to drive Visibox with natural language.

Source: https://manual.spaceage.tv/5.0.0/integrations/cli/