📡 obsctl

Drive OBS Studio from your terminal. No mouse, no clicking around. 🖱️🚫

A snappy dashboard, a scriptable CLI, and a little daemon that keeps the OBS connection warm.

curl -fsSL https://worxbend.github.io/obsctl/install.sh | sh

🎛️ Control · 📊 Watch · 🤖 Automate · 🔁 Stay connected

Website · Install · First 5 minutes · Cheat sheet · Scripting · Docs

_{👆 Not a mockup — every screenshot here is rendered from the real widget code by make readme-shots.}

🤔 What even is this?

You're live. Your mic is hot, your scene is wrong, and OBS is buried behind a game on another monitor. obsctl is OBS in a terminal window:

• 🎛️ A dashboard — scenes, audio levels, profiles, collections, logs and stream health on one screen. Switch scenes with Enter, ride the mic gain with ↑/↓.
• 🤖 A CLI — obsctl scene brb, obsctl mute mic. Perfect for hotkeys, Stream Deck buttons, cron jobs, or a chat bot.
• 🧠 A tiny daemon — one background process holds the OBS connection and reconnects when OBS restarts. Everything else just talks to it. Fast, and no connection storm.

Think of it as kubectl, but for your stream. And it's keyed like Neovim (AstroNvim, specifically), so : runs commands and Space opens a menu of what you can press next.

You'll like it if you: live on a keyboard ⌨️ · run OBS on a small or headless machine 🖥️ · want stream actions in scripts 📜 · think a terminal is a perfectly nice place to be 🧡

⚡ Install

One line. Works on any Linux, any distro — the binaries are static.

curl -fsSL https://worxbend.github.io/obsctl/install.sh | sh

What that actually does (no magic, promise 🙂):

1. 📥 Grabs the right build for your CPU (amd64 or arm64)
2. 🔐 Checks it against the release's SHA256SUMS.txt — if the hash is wrong, nothing gets installed
3. 📁 Drops the binary in ~/.local/bin (or /usr/local/bin if you're root)
4. ✅ Runs it once to make sure it works

[!TIP] Nervous about piping a script into a shell? Good instinct. It's install.sh right here in this repo — read it first, or download and run it yourself.

# a specific release, into a specific folder
curl -fsSL https://worxbend.github.io/obsctl/install.sh | sh -s -- --version v0.6.0 --dir /usr/local/bin

# same thing with environment variables
OBSCTL_VERSION=v0.6.0 OBSCTL_INSTALL_DIR=/usr/local/bin sh install.sh

git clone https://github.com/worxbend/obsctl.git
cd obsctl && shards install && make release
install -Dm755 bin/obsctl ~/.local/bin/obsctl

Check it worked:

obsctl --version

Nothing happened? ~/.local/bin probably isn't on your PATH. Add this to your ~/.bashrc or ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

🐣 Your first five minutes

Never touched obs-websocket before? Start here. Five steps, nothing skipped.

1️⃣ Turn on the OBS WebSocket server

In OBS Studio: Tools ▸ WebSocket Server Settings

• ☑️ Tick Enable WebSocket server
• 🔌 Leave the port at 4455 (that's what obsctl expects)
• 🔑 Click Show Connect Info and copy the password — or untick Enable Authentication if this machine is only yours
• 💾 Hit Apply, then OK

_{Don't see the menu item? You're on OBS older than 28. Update OBS — 28 and up ship obs-websocket 5 built in.}

2️⃣ Create a config file

obsctl init

That writes ~/.config/obsctl/config.yml with sensible defaults. You don't have to edit it yet.

3️⃣ Hand over the password

obsctl never stores your password in a file. Put it in the environment:

export OBS_WEBSOCKET_PASSWORD='the password you copied'

Put that line in your ~/.bashrc / ~/.zshrc so it sticks around. 🔒 No authentication? Skip this — obsctl connects with an empty password.

4️⃣ Start the daemon

In a terminal, leave this running:

obsctl server --headless

You should see a log line like obs_connected connected to OBS 31.0.0. 🎉 (Later, make it automatic: obsctl service install && obsctl service start.)

5️⃣ Open the dashboard

In a second terminal:

obsctl

That's it — you're in. Now play:

[!NOTE] Nothing on screen or an error? Jump to Something broke? — it's almost always one of three things.

📸 The tour

Press Space and obsctl tells you what's next — the which-key menu, exactly like AstroNvim.

Type : for a command line, with completion for every scene and input you have.

29 built-in themes, previewed live before you commit. F2 or <leader>ut.

🎚️ A mixing desk, not a list

Every audio input is a vertical channel strip, the way OBS' own vertical mixer lays them out:

├ ⣾  Audio Matrix  03  [a] Mic/Aux (mic) · ←/→ chan ↑/↓ gain m mute ─┤
┃  mic    desktop   guest                                            ┃
┃ ▔▔▔ │    ▂▂▂ │    ░·░ │        ← peak hold, meter, fader           ┃
┃ ███ ━    ███ │    ░·░ ━                                            ┃
┃ ███ ┃    ███ ━    ░●░ ┃                                            ┃
┃-4.2 dB  -12.4 dB    –∞                                             ┃
┃  72%      48%      60%                                             ┃
┃ ♪ LIVE   ♪ LIVE   ✖ MUTE                                           ┃

The meter fills bottom-up in eighth-height blocks, so it reads eight times finer than the rows it has, and each cell is coloured by the level it stands for — green up to −20 dBFS, yellow to −9, red above it. The bar over the top is the peak hold: it jumps to your loudest moment and slides back down on its own. A channel that clips flashes its name; a channel that has never sent a reading shows a searching dot, so silent and not there don't look alike. 🟢🟡🔴

Short on rows? The panel drops the dB readout first, then the gain, then the mute button. The meters are the last thing to go.

📊 Stream health, while you're live

When the stream starts, a Stats panel opens next to the logs:

├ 📊  Stats  352   dropped frames ──────────────┤
│ ⚡ 59.94 fps  █████▇██  ⏱ 1.42 ms             │
│ ▸ RENDER missed     12 / 128,400   0.01%      │
│ ▸ OUTPUT skipped   340 / 128,000   0.27%      │
│ ◆ HEALTH         nominal  · budget 9%         │

Frames missed to rendering lag, frames skipped to encoding lag, and how much of each frame's budget you're burning. Green is fine, yellow means look at it, red means your viewers are already seeing it. 🟢🟡🔴

🎹 Cheat sheet

The dashboard is keyed like AstroNvim: : is the command line, Space is the leader, and the motions are vim's.

Moving around

On the audio matrix the axes follow the desk, not the list — the strips stand side by side, so the keys do too:

The leader menu (Space)

Press Space and a menu appears showing every next key. No memorising.

Esc (or any key that leads nowhere) closes it. The old single letters — s a p c r D R — still work too.

The command line (:)

:scene "Main Camera"      :vol "Desktop Audio" 65
:mute Mic/Aux             :profile Streaming
:stream                   :collection Gaming
:rec start                :status
:q                        :h

Yes, :q, :qa, :wq and :x all quit. :h lists everything. 😄

🖱️ Mouse works too

🤖 Scripting

Everything the dashboard does, the CLI does — and it's built to be called from scripts, hotkeys, and bots.

# Scenes and audio
obsctl scene brb                    # aliases and shortcuts work
obsctl mute mic
obsctl volume "Desktop Audio" 70

# Outputs
obsctl stream                       # toggle streaming
obsctl record start                 # start | stop | toggle | pause | resume | status

# What's going on?
obsctl status
obsctl doctor                       # checks everything, tells you how to fix it 🩺

# Live event feed, one JSON object per line
obsctl watch --topics state | jq -r '.data.current_scene'

# Tab completion for your shell
obsctl completions zsh > ~/.zfunc/_obsctl

📦 JSON for robots

Add --json to any scriptable command and get exactly one envelope on stdout:

obsctl scene main --json

{"ok": true, "result": {"message": "scene set: Main Camera"}, "error": null, "exit_code": 0}

Exit codes are stable, so if obsctl scene main; then … just works:

🎨 Make it yours

~/.config/obsctl/config.yml — short, human, and validated:

version: 1

connection:
  host: 127.0.0.1
  port: 4455
  password_env: OBS_WEBSOCKET_PASSWORD   # 🔒 the name of the variable, never the password

reconnect:
  enabled: true
  endless: true

ui:
  theme: ember          # 29 to choose from, or roll your own colours
  advanced_ui: true     # false = plain ASCII, no fancy glyphs
  show_icons: true
  locale: en            # en | uk

scenes:
  - name: Main Camera
    alias: main         # so you can type `obsctl scene main`
    shortcut: "1"

audio:
  inputs:
    - name: Mic/Aux
      alias: mic
      shortcut: m

💡 Shortcut: run obsctl dump-config once you're connected and obsctl fills in your real scene and input names for you. It keeps your settings and makes a backup.

Handy commands: obsctl config explain (where every setting came from) · obsctl config diff (what you changed) · obsctl validate-config (is it sane?). Full reference: docs/config.md.

🔁 Keep the daemon running

Don't babysit a terminal — let systemd do it:

obsctl service install
obsctl service start
obsctl service status

No root needed; it's a --user unit at ~/.config/systemd/user/obsctl.service. stop, restart, and uninstall do what you'd expect.

🩺 Something broke?

Start here — it fixes most things:

obsctl doctor

It checks your config, credentials, socket, daemon, OBS connection, and service unit, and prints a fix for anything it doesn't like.

Still stuck? Turn up the volume and read along:

obsctl --log-level debug server --headless

Logs also land in ~/.local/state/obsctl/obsctl.log. Passwords are redacted from both, so they're safe to paste into an issue. 🔐

🧠 How it works

One process owns the OBS connection. Everyone else asks it nicely.

flowchart LR
    OBS["🎥 OBS Studio<br/>obs-websocket 5.x"]
    D["🧠 obsctl server<br/>the only connection owner"]
    T["🎛️ dashboard"]
    C["⚙️ CLI / scripts"]
    S["🛠️ systemd --user"]

    OBS <-->|WebSocket| D
    D <-->|Unix socket| T
    D <-->|Unix socket| C
    S -. keeps alive .-> D

Why bother? Because it means 🔌 exactly one WebSocket per session · 🔄 every client sees the same state instantly · 🧯 reconnect logic lives in one place · ⚡ CLI commands don't pay for a handshake every time.

The socket lives in $XDG_RUNTIME_DIR/obsctl/ (falling back to /tmp/obsctl-$UID/). Nothing listens on the network — this is a local tool.

Under the hood it's Crystal, and the TUI is drawn with CryTUI, an in-tree immediate-mode library inspired by Ratatui, tested against memory, ANSI, and real PTY backends.

📚 More docs

🤝 Contributing

Bugs, docs, ideas, code — all welcome. 🙌

shards install
make check      # format + lint + build + test, the same four gates CI runs

The test suite is deterministic and doesn't need OBS running — there's a fake obs-websocket server, real Unix sockets, and real PTYs in the repo. Add a regression test at the narrowest layer that catches your bug, and you're golden.

Changed a widget or a theme? Redraw the pictures:

make readme-shots     # the screenshots above
make site-frames      # the website's terminal frames

Filing an issue? Include your OBS and obs-websocket versions, your terminal and $TERM, what you ran, what you expected, and what you got. For rendering issues, terminal size and font help a lot. Never paste passwords or auth strings — and for security holes, use SECURITY.md instead of a public issue. 🔒

📜 License

MIT. Do what you like with it.