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 integration for quick one-offs, shell aliases, scripting, and hotkey tools.

The CLI is a thin wrapper over the same HTTP REST 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 visibox command and shows you where it landed. On a new terminal you can immediately run visibox health 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.

note

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

Quick Start

# Is Visibox running?
visibox health

# What's playing?
visibox status

# Control playback
visibox play
visibox stop
visibox next
visibox 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 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. 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 abc123
visibox 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

# Fire off a panic reload from a Stream Deck button, keyboard shortcut tool, or hotkey app
visibox 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 30
done

# Dump a set list for a show document
visibox songs --json | jq -r '.[] | "\(.index). \(.title)"'

# Trigger the first Clip of every Song in sequence — hands-off preview
visibox songs --json | jq -r '.[].id' | while read songId; do
  visibox song "$songId"
  visibox play-clip 0
  sleep 15
done

tip

The CLI, the Stream Deck plugin, and AI Assistants 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.