2025-05-01 20:34:52 +01:00
2025-06-04 18:03:29 +01:00
2025-06-03 16:59:50 +01:00
2025-06-04 15:25:14 +01:00
2025-04-19 20:15:26 +01:00
2025-06-04 15:24:48 +01:00
2025-04-28 10:55:42 +01:00

obsws-cli

Hatch project Ruff

A command line interface for OBS Websocket v5

For an outline of past/future changes refer to: CHANGELOG


Table of Contents

Requirements

Installation

with uv
uv tool install obsws-cli
with pipx
pipx install obsws-cli

The CLI should now be discoverable as obsws-cli

Configuration

Flags

  • --host/-H: Websocket host
  • --port/-P Websocket port
  • --password/-p: Websocket password
  • --timeout/-T: Websocket timeout
  • --version/-v: Print the obsws-cli version

Pass --host, --port and --password as flags on 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
OBS_HOST=localhost
OBS_PORT=4455
OBS_PASSWORD=<websocket password>

Flags can be used to override environment variables.

Root Typer

  • obs-version: Get the OBS Client and WebSocket versions.
obsws-cli obs-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.

    optional

    • args: <scene_name>
      • defaults to current scene
obsws-cli sceneitem list

obsws-cli sceneitem list LIVE
  • show: Show an item in a scene.
    • flags:

      optional

      • --group: Parent group name
    • args: <scene_name> <item_name>

obsws-cli sceneitem show START "Colour Source"
  • hide: Hide an item in a scene.
    • flags:

      optional

      • --group: Parent group name
    • args: <scene_name> <item_name>

obsws-cli sceneitem hide START "Colour Source"
  • toggle: Toggle an item in a scene.
    • flags:

      optional

      • --group: Parent group name
    • args: <scene_name> <item_name>

obsws-cli sceneitem toggle --group=test_group START "Colour Source 3"
  • visible: Check if an item in a scene is visible.
    • flags:

      optional

      • --group: Parent group name
    • args: <scene_name> <item_name>

obsws-cli sceneitem visible --group=test_group START "Colour Source 4"
  • transform: Set the transform of an item in a scene.
    • flags:

      optional

      • --group: Parent group name.

      • --alignment: Alignment of the item in the scene

      • --bounds-alignment: Bounds alignment of the item in the scene

      • --bounds-height: Height of the item in the scene

      • --bounds-type: Type of bounds for the item in the scene

      • --bounds-width: Width of the item in the scene

      • --crop-to-bounds: Crop the item to the bounds

      • --crop-bottom: Bottom crop of the item in the scene

      • --crop-left: Left crop of the item in the scene

      • --crop-right: Right crop of the item in the scene

      • --crop-top: Top crop of the item in the scene

      • --position-x: X position of the item in the scene

      • --position-y: Y position of the item in the scene

      • --scale-x: X scale of the item in the scene

      • --scale-y: Y scale of the item in the scene

    • args: <scene_name> <item_name>

obsws-cli sceneitem transform \
    --rotation=5 \
    --position-x=250.8 \
    Scene "Colour Source 3"

Scene Collections

  • list: List all scene collections.
obsws-cli scenecollection list
  • current: Get the current scene collection.
obsws-cli scenecollection current
  • switch: Switch to a scene collection.
    • args: <scene_collection_name>
obsws-cli scenecollection switch test-collection
  • create: Create a new scene collection.
    • args: <scene_collection_name>
obsws-cli scenecollection create test-collection

Group

  • list: List groups in a scene.

    optional

    • args: <scene_name>
      • defaults to current scene
obsws-cli group list

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
  • directory: Get or set the recording directory.

    optional

    • args: <record_directory>
      • if not passed the current record directory will be printed.
obsws-cli record directory

obsws-cli record directory "/home/me/obs-vids/"
obsws-cli record directory "C:/Users/me/Videos"

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

Profile

  • list: List profiles.
obsws-cli profile list
  • current: Get the current profile.
obsws-cli profile current
  • switch: Switch to a profile.
    • args: <profile_name>
obsws-cli profile switch test-profile
  • create: Create a new profile.
    • args: <profile_name>
obsws-cli profile create test-profile
  • remove: Remove a profile.
    • args: <profile_name>
obsws-cli profile remove test-profile

Replay Buffer

  • start: Start the replay buffer.
obsws-cli replaybuffer start
  • stop: Stop the replay buffer.
obsws-cli replaybuffer stop
  • status: Get the status of the replay buffer.
obsws-cli replaybuffer status
  • save: Save the replay buffer.
obsws-cli replaybuffer save

Studio Mode

  • enable: Enable studio mode.
obsws-cli studiomode enable
  • disable: Disable studio mode.
obsws-cli studiomode disable
  • toggle: Toggle studio mode.
obsws-cli studiomode toggle
  • status: Get the status of studio mode.
obsws-cli studiomode status

Virtual Cam

  • start: Start virtual camera.
obsws-cli virtualcam start
  • stop: Stop virtual camera.
obsws-cli virtualcam stop
  • toggle: Toggle virtual camera.
obsws-cli virtualcam toggle
  • status: Get the status of the virtual camera.
obsws-cli virtualcam status

Hotkey

  • list: List all hotkeys.
obsws-cli hotkey list
  • trigger: Trigger a hotkey by name.
obsws-cli hotkey trigger OBSBasic.StartStreaming

obsws-cli hotkey trigger OBSBasic.StopStreaming
  • trigger-sequence: Trigger a hotkey by sequence.
    • flags:

      optional

      • --shift: Press shift.
      • --ctrl: Press control.
      • --alt: Press alt.
      • --cmd: Press command (mac).
    • args: <key_id>

obsws-cli hotkey trigger-sequence OBS_KEY_F1 --ctrl

obsws-cli hotkey trigger-sequence OBS_KEY_F1 --shift --ctrl

Filter

  • list: List filters for a source.

    optional

    • args: <source_name>
      • defaults to current scene
obsws-cli filter list "Mic/Aux"
  • enable: Enable a filter for a source.
    • args: <source_name> <filter_name>
obsws-cli filter enable "Mic/Aux" "Gain"
  • disable: Disable a filter for a source.
    • args: <source_name> <filter_name>
obsws-cli filter disable "Mic/Aux" "Gain"
  • toggle: Toggle a filter for a source.
    • args: <source_name> <filter_name>
obsws-cli filter toggle "Mic/Aux" "Gain"
  • status: Get the status of a filter for a source.
    • args: <source_name> <filter_name>
obsws-cli filter status "Mic/Aux" "Gain"

Projector

  • list-monitors: List available monitors.
obsws-cli projector list-monitors
  • open: Open a fullscreen projector for a source on a specific monitor.

    • flags:

      optional

      • --monitor-index: Index of the monitor to open the projector on.
        • defaults to 0

    optional

    • args: <source_name>
      • defaults to current scene
obsws-cli projector open

obsws-cli projector open --monitor-index=1 "test_scene"

obsws-cli projector open --monitor-index=1 "test_group"

Screenshot

  • save: Take a screenshot and save it to a file.
    • flags:

      optional

      • --width:
        • defaults to 1920
      • --height:
        • defaults to 1080
      • --quality:
        • defaults to -1
    • args: <source_name> <output_path>

obsws-cli screenshot save --width=2560 --height=1440 "Scene" "C:\Users\me\Videos\screenshot.png"

License

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

Description
No description provided
Readme 483 KiB
Languages
Python 100%