obsws-cli/README.md

obsws-cli

---

Table of Contents

• Installation
• Configuration
• Commands
• License

Requirements

• Python 3.10 or greater
• OBS Studio 28+

Installation

with uv

uv tool install .

with pipx

pipx install .

The CLI should now be discoverable as obsws-cli

Configuration

Flags

Pass --host, --port and --password as flags to the root command, for example:

obsws-cli --host=localhost --port=4455 --password=<websocket password> --help

Environment Variables

Store and load environment variables from:

• A .env file in the cwd
• user home directory / .config / obsws-cli / obsws.env

OBSWS_HOST=localhost
OBSWS_PORT=4455
OBSWS_PASSWORD=<websocket password>

Flags can be used to override environment variables.

Root Typer

• version: Get the OBS Client and WebSocket versions.

obsws-cli version

Sub Typers

Scene

• list: List all scenes.

obsws-cli scene list

• current: Get the current program scene.

obsws-cli scene current

• switch: Switch to a scene.
  • args: <scene_name>

obsws-cli scene switch LIVE

Scene Item

• list: List all items in a scene.
  • args: <scene_name>

obsws-cli scene-item list LIVE

• show: Show an item in a scene.

  • flags:

    optional

    • --parent: Parent group name

  • args: <scene_name> <item_name>

obsws-cli scene-item show START "Colour Source"

• hide: Hide an item in a scene.

  • flags:

    optional

    • --parent: Parent group name

  • args: <scene_name> <item_name>

obsws-cli scene-item hide START "Colour Source"

• toggle: Toggle an item in a scene.

  • flags:

    optional

    • --parent: Parent group name

  • args: <scene_name> <item_name>

obsws-cli scene-item toggle --parent=test_group START "Colour Source 3"

• visible: Check if an item in a scene is visible.

  • flags:

    optional

    • --parent: Parent group name

  • args: <scene_name> <item_name>

obsws-cli scene-item visible --parent=test_group START "Colour Source 4"

Scene Collections

• list: List all scene collections.

obsws-cli scene-collection list

• current: Get the current scene collection.

obsws-cli scene-collection current

• switch: Switch to a scene collection.
  • args: <scene_collection_name>

obsws-cli scene-collection switch test-collection

• create: Create a new scene collection.
  • args: <scene_collection_name>

obsws-cli scene-collection create test-collection

Group

• list: List groups in a scene.
  • args: <scene_name>

obsws-cli group list START

• show: Show a group in a scene.
  • args: <scene_name> <group_name>

obsws-cli group show START "test_group"

• hide: Hide a group in a scene.
  • args: <scene_name> <group_name>

obsws-cli group hide START "test_group"

• toggle: Toggle a group in a scene.
  • args: <scene_name> <group_name>

obsws-cli group toggle START "test_group"

• status: Get the status of a group in a scene.
  • args: <scene_name> <group_name>

obsws-cli group status START "test_group"

Input

• list: List all inputs.

  • flags:

    optional

    • --input: Filter by input type.
    • --output: Filter by output type.
    • --colour: Filter by colour source type.

obsws-cli input list

obsws-cli input list --input --colour

• mute: Mute an input.
  • args: <input_name>

obsws-cli input mute "Mic/Aux"

• unmute: Unmute an input.
  • args: <input_name>

obsws-cli input unmute "Mic/Aux"

• toggle: Toggle an input.

obsws-cli input toggle "Mic/Aux"

Record

• start: Start recording.

obsws-cli record start

• stop: Stop recording.

obsws-cli record stop

• status: Get recording status.

obsws-cli record status

• toggle: Toggle recording.

obsws-cli record toggle

• resume: Resume recording.

obsws-cli record resume

• pause: Pause recording.

obsws-cli record pause

Stream

• start: Start streaming.

obsws-cli stream start

• stop: Stop streaming.

obsws-cli stream stop

• status: Get streaming status.

obsws-cli stream status

• toggle: Toggle streaming.

obsws-cli stream toggle

License

obsws-cli is distributed under the terms of the MIT license.