gobs-cli

A command line interface for OBS Websocket v5

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

Installation

go install github.com/onyx-and-iris/gobs-cli@latest

Configuration

Flags

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

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

gobs-cli --host localhost --port 4455 --password 'websocket password' --help

Environment Variables

Store and load environment variables from:

• A .env file in the cwd
• $XDG_CONFIG_HOME / gobs-cli / config.env (see os.UserConfigDir)

OBS_HOST=localhost
OBS_PORT=4455
OBS_PASSWORD=<websocket password>
OBS_TIMEOUT=5

Commands

ObsVersionCmd

• Print OBS client and websocket version.

gobs-cli obs-version

SceneCmd

• list: List all scenes.

gobs-cli scene list

• current: Get the current scene.

  • flags:

    optional

    • --preview: Preview scene.

gobs-cli scene current

gobs-cli scene current --preview

• switch: Switch to a scene.

  • flags:

    optional

    • --preview: Preview scene.

  • args: SceneName

gobs-cli scene switch LIVE

gobs-cli scene switch --preview LIVE

SceneItemCmd

• list: List all scene items.

  optional

  • args: SceneName
    • defaults to current scene

gobs-cli sceneitem list

gobs-cli sceneitem list LIVE

• show: Show scene item.

  • flags:

    optional

    • --group: Parent group name.

  • args: SceneName ItemName

gobs-cli sceneitem show START "Colour Source"

• hide: Hide scene item.

  • flags:

    optional

    • --group: Parent group name.

  • args: SceneName ItemName

gobs-cli sceneitem hide START "Colour Source"

• toggle: Toggle scene item.

  • flags:

    optional

    • --group: Parent group name.

  • args: SceneName ItemName

gobs-cli sceneitem toggle --group=test_group START "Colour Source 3"

• visible: Get scene item visibility.

  • flags:

    optional

    • --group: Parent group name.

  • args: SceneName ItemName

gobs-cli sceneitem visible --group=test_group START "Colour Source 4"

• transform: Transform scene item.

  • flags:

    optional

    • --group: Parent group name.

    • --alignment: Alignment of the scene item.

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

    • --bounds-height: Bounds height of the scene item.

    • --bounds-type: Bounds type of the scene item.

    • --bounds-width: Bounds width of the scene item.

    • --crop-to-bounds: Whether to crop the scene item to bounds.

    • --crop-bottom: Crop bottom value of the scene item.

    • --crop-left: Crop left value of the scene item.

    • --crop-right: Crop right value of the scene item.

    • --crop-top: Crop top value of the scene item.

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

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

    • --rotation: Rotation of the scene item.

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

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

  • args: SceneName ItemName

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

GroupCmd

• list: List all groups.

  optional

  • args: SceneName
    • defaults to current scene

gobs-cli group list

gobs-cli group list START

• show: Show group details.
  • args: SceneName GroupName

gobs-cli group show START "test_group"

• hide: Hide group.
  • args: SceneName GroupName

gobs-cli group hide START "test_group"

• toggle: Toggle group.
  • args: SceneName GroupName

gobs-cli group toggle START "test_group"

• status: Get group status.
  • args: SceneName GroupName

gobs-cli group status START "test_group"

InputCmd

• list: List all inputs.

  • flags:

    optional

    • --input: List all inputs.
    • --output: List all outputs.
    • --colour: List all colour sources.

gobs-cli input list

gobs-cli input list --input --colour

• mute: Mute input.
  • args: InputName

gobs-cli input mute "Mic/Aux"

• unmute: Unmute input.
  • args: InputName

gobs-cli input unmute "Mic/Aux"

• toggle: Toggle input.
  • args: InputName

gobs-cli input toggle "Mic/Aux"

RecordCmd

• start: Start recording.

gobs-cli record start

• stop: Stop recording.

gobs-cli record stop

• status: Get recording status.

gobs-cli record status

• toggle: Toggle recording.

gobs-cli record toggle

• pause: Pause recording.

gobs-cli record pause

• resume: Resume recording.

gobs-cli record resume

• directory: Get/Set recording directory.

  optional

  • args: RecordDirectory
    • if not passed the current record directory will be printed.

gobs-cli record directory

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

StreamCmd

• start: Start streaming.

gobs-cli stream start

• stop: Stop streaming.

gobs-cli stream stop

• status: Get streaming status.

gobs-cli stream status

• toggle: Toggle streaming.

gobs-cli stream toggle

SceneCollectionCmd

• list: List scene collections.

gobs-cli scenecollection list

• current: Get current scene collection.

gobs-cli scenecollection current

• switch: Switch scene collection.
  • args: Name

gobs-cli scenecollection switch test-collection

• create: Create scene collection.
  • args: Name

gobs-cli scenecollection create test-collection

ProfileCmd

• list: List profiles.

gobs-cli profile list

• current: Get current profile.

gobs-cli profile current

• switch: Switch profile.
  • args: Name

gobs-cli profile switch test-profile

• create: Create profile.
  • args: Name

gobs-cli profile create test-profile

• remove: Remove profile.
  • args: Name

gobs-cli profile remove test-profile

ReplayBufferCmd

• start: Start replay buffer.

gobs-cli replaybuffer start

• stop: Stop replay buffer.

gobs-cli replaybuffer stop

• toggle: Toggle replay buffer.

gobs-cli replaybuffer toggle

• status: Get replay buffer status.

gobs-cli replaybuffer status

• save: Save replay buffer.

gobs-cli replaybuffer save

StudioModeCmd

• enable: Enable studio mode.

gobs-cli studiomode enable

• disable: Disable studio mode.

gobs-cli studiomode disable

• toggle: Toggle studio mode.

gobs-cli studiomode toggle

• status: Get studio mode status.

gobs-cli studiomode status

VirtualCamCmd

• start: Start virtual camera.

gobs-cli virtualcam start

• stop: Stop virtual camera.

gobs-cli virtualcam stop

• toggle: Toggle virtual camera.

gobs-cli virtualcam toggle

• status: Get virtual camera status.

gobs-cli virtualcam status

HotkeyCmd

• list: List all hotkeys.

gobs-cli hotkey list

• trigger: Trigger a hotkey by name.

gobs-cli hotkey trigger OBSBasic.StartStreaming

gobs-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: keyID

    • Check obs-hotkeys.h for a full list of OBS key ids.

gobs-cli hotkey trigger-sequence OBS_KEY_F1 --ctrl

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

FilterCmd

• list: List all filters.

  optional

  • args: SourceName
    • defaults to current scene

gobs-cli filter list

• enable: Enable filter.
  • args: SourceName FilterName

gobs-cli enable 'Mic/Aux' 'Gain'

• disable: Disable filter.
  • args: SourceName FilterName

gobs-cli disable 'Mic/Aux' 'Gain'

• toggle: Toggle filter.
  • args: SourceName FilterName

gobs-cli toggle 'Mic/Aux' 'Gain'

• status: Get filter status.
  • args: SourceName FilterName

gobs-cli status 'Mic/Aux' 'Gain'

ProjectorCmd

• list-monitors: List available monitors.

gobs-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: SourceName
    • defaults to current scene

gobs-cli projector open

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

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

ScreenshotCmd

• 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: SourceName FilePath

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