gobs-cli

command module
v0.18.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 24, 2026 License: MIT Imports: 28 Imported by: 0

README

gobs-cli

A command line interface for OBS Websocket v5

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

Table of Contents

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

Style

Styling is opt-in, by default you will get a colourless output:

colourless

You may enable styling with the --style/-s flag:

gobs-cli --style="red" sceneitem list

Available styles: red, magenta, purple, blue, cyan, green, yellow, orange, white, grey, navy, black

coloured

Optionally you may disable border colouring with the --no-border flag:

coloured-no-border

gobs-cli --style="red" --no-border sceneitem list

Or with environment variables:

GOBS_STYLE=red
GOBS_STYLE_NO_BORDER=true

Commands

ObsVersionCmd
  • Print OBS client and websocket version.
gobs-cli obs-version
SceneCmd
  • list: List all scenes.

    • flags:

      optional

      • --UUID: Display UUIDs of 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.

    • flags:

      optional

      • --UUID: Display UUIDs of 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
  • create: Create input.
    • args: Name Kind
gobs-cli input create 'stream mix' 'wasapi_input_capture'
  • remove: Remove input.
    • args: Name
gobs-cli input remove 'stream mix'
  • list: List all inputs.

    • flags:

      optional

      • --input: List all inputs.
      • --output: List all outputs.
      • --colour: List all colour sources.
      • --ffmpeg: List all ffmpeg sources.
      • --vlc: List all VLC sources.
      • --uuid: Display UUIDs of inputs.
gobs-cli input list

gobs-cli input list --input --colour
  • list-kinds: List input kinds.
gobs-cli input list-kinds
  • 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"
  • volume: Set input volume.
    • args: InputName Volume
gobs-cli input volume -- 'Mic/Aux' -30.6

  • show: Show input details.

    • args: Name

    • flags:

      optional

      • --verbose: List all available input devices.

  • update: Update input settings.

    • args: InputName DeviceName
gobs-cli input update 'Mic/Aux' 'Voicemeeter Out B1 (VB-Audio Voicemeeter VAIO)'
  • kind-defaults: Get default settings for an input kind.
    • args: Kind
gobs-cli input kind-defaults 'wasapi_input_capture'
TextCmd
  • current: Display current text for a text input.
    • args: InputName
gobs-cli text current "My Text Input"
  • update: Update the text of a text input.
    • args: InputName NewText
gobs-cli text update "My Text Input" "hi OBS!"
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"
  • split: Split recording.
gobs-cli record split

  • chapter: Create a chapter in the recording.

    optional

    • arg: ChapterName
gobs-cli record chapter "Chapter Name"
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

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"
SettingsCmd
  • show: Show settings.

    • flags:

      optional

      • --video: Show video settings.
      • --record: Show record directory.
      • --profile: Show profile parameters.
gobs-cli settings show --video --record
  • profile: Get/Set profile parameter setting.
    • args: Category Name Value
gobs-cli settings profile SimpleOutput VBitrate

gobs-cli settings profile SimpleOutput VBitrate 6000

  • stream-service: Get/Set stream service setting.

    • flags:
      • --key: Stream key.
      • --server: Stream server URL.

    optional

    • args: Type
gobs-cli settings stream-service

gobs-cli settings stream-service --key='live_xyzxyzxyzxyz' rtmp_common
  • video: Get/Set video setting.

    • flags:

      optional

      • --base-width: Base (canvas) width.
      • --base-height: Base (canvas) height.
      • --output-width: Output (scaled) width.
      • --output-height: Output (scaled) height.
      • --fps-num: Frames per second numerator.
      • --fps-den: Frames per second denominator.
gobs-cli settings video

gobs-cli settings video --base-width=1920 --base-height=1080
MediaCmd
  • cursor: Get/set the cursor position of a media input.

    • args: InputName

      optional

      • TimeString
gobs-cli media cursor "Media"

gobs-cli media cursor "Media" "00:08:30"
  • play: Plays a media input.
gobs-cli media play "Media"
  • pause: Pauses a media input.
gobs-cli media pause "Media"
  • stop: Stops a media input.
gobs-cli media stop "Media"
  • restart: Restarts a media input.
gobs-cli media restart "Media"

Shell Completion

  • completion:

    optional

    • args: Shell
gobs-cli completion

gobs-cli completion bash

Currently supported shells: bash zsh fish. If no shell is passed completion will attempt to detect the current user shell.

License

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

Documentation

Overview

nolint: misspell

Package main provides a command-line interface (CLI) tool for interacting with OBS WebSocket. It allows users to manage various aspects of OBS, such as scenes, inputs, recording, streaming, and more, by leveraging the goobs library for communication with the OBS WebSocket server.

nolint: misspell

nolint: misspell

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.