{"id":29543857,"url":"https://github.com/onyx-and-iris/obsws-cli","last_synced_at":"2025-07-17T14:08:54.148Z","repository":{"id":290054846,"uuid":"969271099","full_name":"onyx-and-iris/obsws-cli","owner":"onyx-and-iris","description":"A command line interface for OBS Websocket v5 ","archived":false,"fork":false,"pushed_at":"2025-07-14T03:28:16.000Z","size":301,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-14T03:36:06.752Z","etag":null,"topics":["cli","obs","obs-cli","obs-remote","obs-websocket"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onyx-and-iris.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-19T19:15:22.000Z","updated_at":"2025-07-14T03:27:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"0c1f038d-cd53-4c6f-9482-a09c39851bfe","html_url":"https://github.com/onyx-and-iris/obsws-cli","commit_stats":null,"previous_names":["onyx-and-iris/obsws-cli"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/onyx-and-iris/obsws-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onyx-and-iris%2Fobsws-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onyx-and-iris%2Fobsws-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onyx-and-iris%2Fobsws-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onyx-and-iris%2Fobsws-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onyx-and-iris","download_url":"https://codeload.github.com/onyx-and-iris/obsws-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onyx-and-iris%2Fobsws-cli/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265614335,"owners_count":23798427,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","obs","obs-cli","obs-remote","obs-websocket"],"created_at":"2025-07-17T14:08:52.763Z","updated_at":"2025-07-17T14:08:54.143Z","avatar_url":"https://github.com/onyx-and-iris.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# obsws-cli\n\n[![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\n\nA command line interface for OBS Websocket v5\n\nFor an outline of past/future changes refer to: [CHANGELOG](CHANGELOG.md)\n\n-----\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Style](#style)\n- [Commands](#root-typer)\n- [License](#license)\n\n## Requirements\n\n-   Python 3.10 or greater\n-   [OBS Studio 28+][obs-studio]\n\n## Installation\n\n##### *with uv*\n\n```console\nuv tool install obsws-cli\n```\n\n##### *with pipx*\n\n```console\npipx install obsws-cli\n```\n\nThe CLI should now be discoverable as `obsws-cli`\n\n## Configuration\n\n#### Flags\n\n-   --host/-H: Websocket host\n-   --port/-P Websocket port\n-   --password/-p: Websocket password\n-   --timeout/-T: Websocket timeout\n-   --version/-v: Print the obsws-cli version\n\nPass `--host`, `--port` and `--password` as flags on the root command, for example:\n\n```console\nobsws-cli --host=localhost --port=4455 --password=\u003cwebsocket password\u003e --help\n```\n\n#### Environment Variables\n\nStore and load environment variables from:\n-   A `.env` file in the cwd\n-   `user home directory / .config / obsws-cli / obsws.env`\n\n```env\nOBS_HOST=localhost\nOBS_PORT=4455\nOBS_PASSWORD=\u003cwebsocket password\u003e\n```\n\nFlags can be used to override environment variables.\n\n## Style\n\nStyling is opt-in, by default you will get a colourless output:\n\n![colourless](./img/colourless.png)\n\nYou may enable styling with the --style/-s flag:\n\n```console\nobsws-cli --style=\"cyan\" sceneitem list\n```\n\nAvailable styles: _red, magenta, purple, blue, cyan, green, yellow, orange, white, grey, navy, black_\n\n![coloured](./img/coloured-border.png)\n\nOptionally you may disable border colouring with the --no-border flag:\n\n![coloured-no-border](./img/coloured-no-border.png)\n\n```console\nobsws-cli --style=\"cyan\" --no-border sceneitem list\n```\n\nOr with environment variables:\n\n```env\nOBS_STYLE=cyan\nOBS_STYLE_NO_BORDER=true\n```\n\n## Root Typer\n\n-   obs-version: Get the OBS Client and WebSocket versions.\n\n```console\nobsws-cli obs-version\n```\n\n## Sub Typers\n\n#### Scene\n\n-   list: List all scenes.\n    -   flags:\n\n        *optional*\n        -   --uuid: Show UUIDs of scenes\n\n```console\nobsws-cli scene list\n```\n\n-   current: Get the current program scene.\n\n```console\nobsws-cli scene current\n```\n\n-   switch: Switch to a scene.\n    -   args: \u003cscene_name\u003e\n\n```console\nobsws-cli scene switch LIVE\n```\n\n#### Scene Item\n\n-   list: List all items in a scene.\n    -   flags:\n\n        *optional*\n        -   --uuid: Show UUIDs of scene items\n\n    *optional*\n    -   args: \u003cscene_name\u003e\n        -   defaults to current scene\n\n```console\nobsws-cli sceneitem list\n\nobsws-cli sceneitem list LIVE\n```\n\n-   show: Show an item in a scene.\n    -   flags:\n\n        *optional*\n        -   --group: Parent group name\n    -   args: \u003cscene_name\u003e \u003citem_name\u003e\n\n```console\nobsws-cli sceneitem show START \"Colour Source\"\n```\n\n-   hide: Hide an item in a scene.\n    -   flags:\n\n        *optional*\n        -   --group: Parent group name\n    -   args: \u003cscene_name\u003e \u003citem_name\u003e\n\n```console\nobsws-cli sceneitem hide START \"Colour Source\"\n```\n\n-   toggle: Toggle an item in a scene.\n    -   flags:\n\n        *optional*\n        -   --group: Parent group name\n    -   args: \u003cscene_name\u003e \u003citem_name\u003e\n\n```console\nobsws-cli sceneitem toggle --group=test_group START \"Colour Source 3\"\n```\n\n-   visible: Check if an item in a scene is visible.\n    -   flags:\n\n        *optional*\n        -   --group: Parent group name\n    -   args: \u003cscene_name\u003e \u003citem_name\u003e\n\n```console\nobsws-cli sceneitem visible --group=test_group START \"Colour Source 4\"\n```\n\n-   transform: Set the transform of an item in a scene.\n    -   flags:\n        \n        *optional*\n        -   --group: Parent group name.\n\n        -   --alignment: Alignment of the item in the scene\n        -   --bounds-alignment: Bounds alignment of the item in the scene\n        -   --bounds-height: Height of the item in the scene\n        -   --bounds-type: Type of bounds for the item in the scene\n        -   --bounds-width: Width of the item in the scene\n        -   --crop-to-bounds: Crop the item to the bounds\n        -   --crop-bottom: Bottom crop of the item in the scene\n        -   --crop-left: Left crop of the item in the scene\n        -   --crop-right: Right crop of the item in the scene\n        -   --crop-top: Top crop of the item in the scene\n        -   --position-x: X position of the item in the scene\n        -   --position-y: Y position of the item in the scene\n        -   --scale-x: X scale of the item in the scene\n        -   --scale-y: Y scale of the item in the scene\n    -   args: \u003cscene_name\u003e \u003citem_name\u003e\n\n```console\nobsws-cli sceneitem transform \\\n    --rotation=5 \\\n    --position-x=250.8 \\\n    Scene \"Colour Source 3\"\n```\n\n#### Scene Collections\n\n-   list: List all scene collections.\n\n```console\nobsws-cli scenecollection list\n```\n\n-   current: Get the current scene collection.\n\n```console\nobsws-cli scenecollection current\n```\n\n-   switch: Switch to a scene collection.\n    -   args: \u003cscene_collection_name\u003e\n\n```console\nobsws-cli scenecollection switch test-collection\n```\n\n-   create: Create a new scene collection.\n    -   args: \u003cscene_collection_name\u003e\n\n```console\nobsws-cli scenecollection create test-collection\n```\n\n#### Group\n\n-   list: List groups in a scene.\n\n    *optional*\n    -   args: \u003cscene_name\u003e\n        -   defaults to current scene\n\n```console\nobsws-cli group list\n\nobsws-cli group list START\n```\n\n-   show: Show a group in a scene.\n    -   args: \u003cscene_name\u003e \u003cgroup_name\u003e\n\n```console\nobsws-cli group show START \"test_group\"\n```\n\n-   hide: Hide a group in a scene.\n    -   args: \u003cscene_name\u003e \u003cgroup_name\u003e\n\n```console\nobsws-cli group hide START \"test_group\"\n```\n\n-   toggle: Toggle a group in a scene.\n    -   args: \u003cscene_name\u003e \u003cgroup_name\u003e\n\n```console\nobsws-cli group toggle START \"test_group\"\n```\n\n-   status: Get the status of a group in a scene.\n    -   args: \u003cscene_name\u003e \u003cgroup_name\u003e\n\n```console\nobsws-cli group status START \"test_group\"\n```\n\n#### Input\n\n-   list: List all inputs.\n    -   flags:\n\n        *optional*\n        -   --input: Filter by input type.\n        -   --output: Filter by output type.\n        -   --colour: Filter by colour source type.\n        -   --ffmpeg: Filter by ffmpeg source type.\n        -   --vlc: Filter by VLC source type.\n        -   --uuid: Show UUIDs of inputs.\n\n```console\nobsws-cli input list\n\nobsws-cli input list --input --colour\n```\n\n-   mute: Mute an input.\n    -   args: \u003cinput_name\u003e\n\n```console\nobsws-cli input mute \"Mic/Aux\"\n```\n\n-   unmute: Unmute an input.\n    -   args: \u003cinput_name\u003e\n\n```console\nobsws-cli input unmute \"Mic/Aux\"\n```\n\n-   toggle: Toggle an input.\n\n```console\nobsws-cli input toggle \"Mic/Aux\"\n```\n\n#### Text\n\n-   current: Get the current text for a text input.\n    -   args: \u003cinput_name\u003e\n\n```console\nobsws-cli text current \"My Text Input\"\n```\n\n-   update: Update the text of a text input.\n    -   args: \u003cinput_name\u003e \u003cnew_text\u003e\n\n```console\nobsws-cli text update \"My Text Input\" \"hi OBS!\"\n```\n\n#### Record\n\n-   start: Start recording.\n\n```console\nobsws-cli record start\n```\n\n-   stop: Stop recording.\n\n```console\nobsws-cli record stop\n```\n\n-   status: Get recording status.\n\n```console\nobsws-cli record status\n```\n\n-   toggle: Toggle recording.\n\n```console\nobsws-cli record toggle\n```\n\n-   resume: Resume recording.\n\n```console\nobsws-cli record resume\n```\n\n-   pause: Pause recording.\n\n```console\nobsws-cli record pause\n```\n\n-   directory: Get or set the recording directory.\n\n    *optional*\n    -   args: \u003crecord_directory\u003e\n        -   if not passed the current record directory will be printed.\n\n```console\nobsws-cli record directory\n\nobsws-cli record directory \"/home/me/obs-vids/\"\nobsws-cli record directory \"C:/Users/me/Videos\"\n```\n\n-   split: Split the current recording.\n\n```console\nobsws-cli record split\n```\n\n-   chapter: Create a chapter in the current recording.\n\n    *optional*\n    -   args: \u003cchapter_name\u003e\n\n```console\nobsws-cli record chapter \"Chapter Name\"\n```\n\n#### Stream\n\n-   start: Start streaming.\n\n```console\nobsws-cli stream start\n```\n\n-   stop: Stop streaming.\n\n```console\nobsws-cli stream stop\n```\n\n-   status: Get streaming status.\n\n```console\nobsws-cli stream status\n```\n\n-   toggle: Toggle streaming.\n\n```console\nobsws-cli stream toggle\n```\n\n#### Profile\n\n-   list: List profiles.\n\n```console\nobsws-cli profile list\n```\n\n-   current: Get the current profile.\n\n```console\nobsws-cli profile current\n```\n\n-   switch: Switch to a profile.\n    -   args: \u003cprofile_name\u003e\n\n```console\nobsws-cli profile switch test-profile\n```\n\n-   create: Create a new profile.\n    -   args: \u003cprofile_name\u003e\n\n```console\nobsws-cli profile create test-profile\n```\n\n-   remove: Remove a profile.\n    -   args: \u003cprofile_name\u003e\n\n```console\nobsws-cli profile remove test-profile\n```\n\n#### Replay Buffer\n\n-   start: Start the replay buffer.\n\n```console\nobsws-cli replaybuffer start\n```\n\n-   stop: Stop the replay buffer.\n\n```console\nobsws-cli replaybuffer stop\n```\n\n-   status: Get the status of the replay buffer.\n\n```console\nobsws-cli replaybuffer status\n```\n\n-   save: Save the replay buffer.\n\n```console\nobsws-cli replaybuffer save\n```\n\n#### Studio Mode\n\n-   enable: Enable studio mode.\n\n```console\nobsws-cli studiomode enable\n```\n\n-   disable: Disable studio mode.\n\n```console\nobsws-cli studiomode disable\n```\n\n-   toggle: Toggle studio mode.\n\n```console\nobsws-cli studiomode toggle\n```\n\n-   status: Get the status of studio mode.\n\n```console\nobsws-cli studiomode status\n```\n\n#### Virtual Cam\n\n-   start: Start virtual camera.\n\n```console\nobsws-cli virtualcam start\n```\n\n-   stop: Stop virtual camera.\n\n```console\nobsws-cli virtualcam stop\n```\n\n-   toggle: Toggle virtual camera.\n\n```console\nobsws-cli virtualcam toggle\n```\n\n-   status: Get the status of the virtual camera.\n\n```console\nobsws-cli virtualcam status\n```\n\n#### Hotkey\n\n-   list: List all hotkeys.\n\n```console\nobsws-cli hotkey list\n```\n\n-   trigger: Trigger a hotkey by name.\n\n```console\nobsws-cli hotkey trigger OBSBasic.StartStreaming\n\nobsws-cli hotkey trigger OBSBasic.StopStreaming\n```\n\n-   trigger-sequence: Trigger a hotkey by sequence.\n    -   flags:\n\n        *optional*\n        -   --shift: Press shift.\n        -   --ctrl: Press control.\n        -   --alt: Press alt.\n        -   --cmd: Press command (mac).\n\n    -   args: \u003ckey_id\u003e\n        -   Check [obs-hotkeys.h][obs-keyids] for a full list of OBS key ids.\n\n```console\nobsws-cli hotkey trigger-sequence OBS_KEY_F1 --ctrl\n\nobsws-cli hotkey trigger-sequence OBS_KEY_F1 --shift --ctrl\n```\n\n#### Filter\n\n-   list: List filters for a source.\n\n    *optional*\n    -   args: \u003csource_name\u003e\n        -   defaults to current scene\n\n```console\nobsws-cli filter list \"Mic/Aux\"\n```\n\n-   enable: Enable a filter for a source.\n    -   args: \u003csource_name\u003e \u003cfilter_name\u003e\n\n```console\nobsws-cli filter enable \"Mic/Aux\" \"Gain\"\n```\n\n-   disable: Disable a filter for a source.\n    -   args: \u003csource_name\u003e \u003cfilter_name\u003e\n\n```console\nobsws-cli filter disable \"Mic/Aux\" \"Gain\"\n```\n\n-   toggle: Toggle a filter for a source.\n    -   args: \u003csource_name\u003e \u003cfilter_name\u003e\n\n```console\nobsws-cli filter toggle \"Mic/Aux\" \"Gain\"\n```\n\n-   status: Get the status of a filter for a source.\n    -   args: \u003csource_name\u003e \u003cfilter_name\u003e\n\n```console\nobsws-cli filter status \"Mic/Aux\" \"Gain\"\n```\n\n#### Projector\n\n-   list-monitors: List available monitors.\n\n```console\nobsws-cli projector list-monitors\n```\n\n-   open: Open a fullscreen projector for a source on a specific monitor.\n    -   flags:\n\n        *optional*\n        -   --monitor-index: Index of the monitor to open the projector on.\n            -   defaults to 0\n\n    *optional*\n    -   args: \u003csource_name\u003e\n        -   defaults to current scene\n\n```console\nobsws-cli projector open\n\nobsws-cli projector open --monitor-index=1 \"test_scene\"\n\nobsws-cli projector open --monitor-index=1 \"test_group\"\n```\n\n#### Screenshot\n\n-   save: Take a screenshot and save it to a file.\n    -   flags:\n\n        *optional*\n        -   --width:\n            -   defaults to 1920\n        -   --height:\n            -   defaults to 1080\n        -   --quality:\n            -   defaults to -1\n\n    -   args: \u003csource_name\u003e \u003coutput_path\u003e\n\n```console\nobsws-cli screenshot save --width=2560 --height=1440 \"Scene\" \"C:\\Users\\me\\Videos\\screenshot.png\"\n```\n\n## License\n\n`obsws-cli` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n\n\n[obs-studio]: https://obsproject.com/\n[obs-keyids]: https://github.com/obsproject/obs-studio/blob/master/libobs/obs-hotkeys.h\n[no-colour]: https://no-color.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonyx-and-iris%2Fobsws-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonyx-and-iris%2Fobsws-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonyx-and-iris%2Fobsws-cli/lists"}