obsx

A CLI for OBS.

Install globally:

npm install -g https://github.com/zeke/obsx/archive/refs/tags/v1.2.2.tar.gz
obsx <command>

This CLI connects to OBS via the built-in obs-websocket server (protocol v5).

• OBS: OBS 28+ (or obs-websocket 5.x installed)
• WebSocket server: enabled in OBS
• Default URL: ws://localhost:4455
• Authentication: none by default

In OBS, look for Tools -> WebSocket Server Settings (or similar) and set the port to 4455.

Connection config is optional; by default it uses ws://localhost:4455 with no password.

To override, set environment variables:

• OBSX_URL (default: ws://localhost:4455)
• OBSX_PASSWORD (optional)

Add a webcam source to the current scene:

obsx add-webcam

Or without installing:

npx https://github.com/zeke/obsx/archive/refs/tags/v1.2.2.tar.gz add-webcam

Interactive mode (hit enter to accept defaults):

obsx add-webcam --interactive

Add image sources for all images in the current directory (skips ones already in the scene):

obsx add-images

Use a specific directory:

obsx add-images --dir "$PWD"

Use natural language to control OBS. This sends your prompt to Claude along with the current state of your OBS instance, and executes the generated commands.

Requires the ANTHROPIC_API_KEY environment variable.

obsx "start recording"
obsx "switch to the BRB scene"
obsx "hide the webcam"
obsx "add a color source called 'Red Background' to the current scene"
obsx "mute the mic"
obsx "set the transition to fade and make it 500ms"
obsx "move the webcam to the bottom right corner"
obsx "take a screenshot of the current scene"
obsx "create a new scene called Interview with two color sources side by side"

Any text that isn't a recognized command is treated as an AI prompt, so obsx yolo "..." also works.

• obs-skill - An agent skill for controlling OBS with natural language. Use this when you want a coding agent to drive OBS directly, rather than a CLI you run yourself.
• obs-mcp - An MCP server for OBS.

Run locally from the repo without publishing:

npm run dev -- <command>

For example:

npm run dev -- add-webcam
npm run dev -- add-webcam --device iphone
npm run dev -- add-images