📡 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

_{👆 An unedited session, sped up 2×. The same recording plays as sharp, scrubbable text on the website — or locally with asciinema play docs/demo/obsctl.cast.}

🤔 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 beacon in the header corner animates differently for idle, recording, on air, and both — so you can tell what OBS is doing at a glance.
• 🤖 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 reads the password from an environment variable — OBS_WEBSOCKET_PASSWORD — and never writes it anywhere itself. 🔒

For right now, type it into this shell only. read -rs means "read a line without printing it", so the password never appears on screen and never lands in your shell history:

printf 'OBS WebSocket password: '
read -rs OBS_WEBSOCKET_PASSWORD
echo
export OBS_WEBSOCKET_PASSWORD

That lasts until you close the terminal, which is exactly what you want while you're finding your feet. No authentication turned on? Skip this entirely — obsctl connects with an empty password.

[!WARNING] Don't put that export line in ~/.bashrc or ~/.zshrc. Shell startup files are usually world-readable (mode 644), they very often end up in a public dotfiles repository, and a variable exported there is handed to every program you launch from that shell — not just obsctl. A password that only the daemon needs shouldn't be sitting in the environment of your text editor.

# pass (https://www.passwordstore.org/)
OBS_WEBSOCKET_PASSWORD="$(pass show obs/websocket)" obsctl server --headless

# GNOME Keyring / any libsecret store
OBS_WEBSOCKET_PASSWORD="$(secret-tool lookup service obs-websocket)" obsctl server --headless

# 1. write the password into a file only you can read
mkdir -p ~/.config/obsctl
touch ~/.config/obsctl/obsctl.env
chmod 600 ~/.config/obsctl/obsctl.env
printf 'OBS WebSocket password: '
read -rs pw
echo
printf 'OBS_WEBSOCKET_PASSWORD=%s\n' "$pw" > ~/.config/obsctl/obsctl.env
unset pw

# 2. tell the service unit to read it
mkdir -p ~/.config/systemd/user/obsctl.service.d
cat > ~/.config/systemd/user/obsctl.service.d/password.conf <<'CONF'
[Service]
EnvironmentFile=%h/.config/obsctl/obsctl.env
CONF
systemctl --user daemon-reload
systemctl --user restart obsctl

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

Everything below happens in the recording at the top of this page — it's the whole tour, and it's deliberately the only showcase here. A screenshot goes stale the moment a panel is redrawn and nothing catches it; a recording gets re-made from the code it documents. 🎬

• 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.
• 41 built-in themes, previewed live before you commit. F2 or <leader>ut. Twelve of them are vivid: near-black grounds under a gradient that swings across the colour wheel — violet into toxic green, orange into gold, cyan into hot pink. The website will repaint itself in eight of them if you click a swatch.

🎚️ 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.

🎬 Switch scenes in two keys (<leader>s)

Press Space then s. Every scene appears with one key next to it — and that key switches to it. No cursor, no Enter.

╭─ 🎬  Switch scene  03  ↑↓ move  ↵ switch  esc close ─╮
│ 1  Main Camera                                       │
│ 2  Screen Share                                      │
│ 3  BRB                                               │
╰──────────────────────────────────────────────────────╯

Space s 2 and you're on Screen Share. Three keystrokes, mid-stream.

Two things worth knowing:

• The picker takes every key while it's open. q doesn't quit and m doesn't mute — they're scene labels in here. Only Esc leaves. A key that isn't a label does nothing at all, so a typo costs you a keystroke and not your place.
• Your configured shortcuts win. If a scene has shortcut: b in your config, it keeps b here, and the automatic labels work around it. The key the scenes panel shows you as [b] is the key that works. Shortcuts longer than one character (brb) still work on the command line and in the CLI — they just can't be a single press.

🗂 Hide the scenes you never switch to (<leader>P)

Scene lists grow. Half of a real OBS collection is scenes that exist only to be nested inside another scene — a lower third, a looping background, a camera group. They are scenes as far as OBS is concerned, but you never switch to one, and every time you scroll past them you're scrolling past furniture.

A scene profile is a name plus the scenes to keep out of the list. It is obsctl's own idea, saved in your obsctl config file — not an OBS profile and not an OBS scene collection. Those two are OBS's, the dashboard shows them in their own panels, and a profile never touches either.

The daemon owns them, so a profile you switch on here also applies to obsctl scene-profile on the command line and to a second dashboard, without either having to reload.

Press Space then P. Every scene shows up, including the hidden ones — this is the one place that lists them, because it's the one place that can bring them back. Hidden scenes are dimmed and carry a hollow ○ instead of a filled ●:

╭─ 🗂  Edit profile  streaming ──────────────────────────╮
│ ●  Main Camera                                        │
│ ●  Screen Share                                       │
│ ○  Utility Cam                                        │
│ ○  BRB Loop                                           │
│ t hide · n name · ⇥ load profile · ↵ save · esc close  │
╰───────────────────────────────────────────────────────╯

The bottom row is every key the editor answers to, including the one that loads a profile you've already saved into the draft — the title is where the profile's name goes, and a name of any length would have pushed the keys off the end of it.

Three things worth knowing:

• Nothing is saved until Enter. Toggling scenes builds up a draft that lives in the dashboard; Enter sends it to the daemon, which writes it to your config file, and Esc throws it away. Loading another profile with Tab replaces the draft too, and says so in the title.
• Saving doesn't switch to it. The editor lets you work on a profile you're not currently using, and having the scene list change under you would be a surprise. <leader>p is how you put one into effect.
• Renaming a profile renames it. If you load streaming with Tab, press n and type podcast, saving moves that profile to the new name and leaves it where it was in the list — you get one profile called podcast, not two. A name another profile already has is refused, because two profiles can't share one.
• A profile changes which scenes are drawn, not which exist. OBS still has every scene and obsctl scene "Utility Cam" still switches to a hidden one from the command line. Wherever a scene list is drawn a hidden scene is hidden — the <leader>s picker and the palette's completions both go by the list you can see — so <leader>p 0 is how you get it back on screen. Hiding is a view, not a lock.

🗂 Pick a profile, or put every scene back (<leader>p)

Building a profile is one key; living with them is the other. Press Space then a lower-case p and every profile you've saved is on screen, with the one in effect marked ▶ and the number of scenes it hides beside its name. The top row isn't a profile at all — it's the way back to the full list:

╭─ 🗂  Scene profiles  03   ↵ use · esc close ──────────────╮
│ 0  ◇  Show every scene                                   │
│ 1  ▶  streaming · hides 2                                │
│ 2  ◇  editing · hides 0                                  │
│ ↵ use · e edit · r rename · n new · d delete · esc close │
╰──────────────────────────────────────────────────────────╯

Press 1 and the scene list is streaming's. Press 0 and every scene is back. The row numbers are the keys, so nothing has to be remembered.

Three things worth knowing:

• d asks before it deletes. The first press turns the bottom row into delete “streaming”? · d confirm · esc cancel, naming the profile you're about to lose. The second d does it; any other key calls it off, Enter included — it means "use this row" everywhere else in the list, so it isn't allowed to be the press that destroys a profile — as does a stray click. Deleting the profile that was in effect puts every scene back rather than leaving the list filtered by something that's gone.
• This one takes effect as you go. Unlike the editor, where nothing is sent until Enter, activating a row or confirming a delete asks the daemon straight away — so the profile you were using is still the profile you're using after a restart, and the CLI agrees. If the daemon refuses, the status line says why.
• You can always see which one is on. The scenes panel title reads Scenes · streaming instead of Scenes, and the header adds 🗂 scene profile: streaming next to the OBS profile. A short scene list is never a mystery.

The saved shape lives under the top-level scene_profiles key; docs/config.md describes it field by field, and editing it by hand is as supported as editing it from the dashboard. From a shell, obsctl scene-profile lists them, obsctl scene-profile <name> switches, and obsctl scene-profile --off puts every scene back — see docs/commands.md.

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          # 41 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 theme? Re-export the palettes the website styles itself from (CI fails if the committed copy is stale):

make site-themes      # site/themes.js, read from the real theme table

Changed the dashboard enough that the demo no longer matches? Re-record it — docs/demo/README.md has the exact commands, including how to trim the recording and regenerate the GIF above. 🎬

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.