fix environment name

add link to style section in ToC.

add imgs.

.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    environment: pypi
+    permissions:
+      # This permission is needed for private repositories.
+      contents: read
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip 
+          pip install hatch
+
+      - name: Build package
+        run: hatch build
+
+      - name: Publish on PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/ruff.yml

@@ -0,0 +1,19 @@
+name: Ruff
+
+on:
+  push:
+    branches: [main]
+
+  pull_request:
+    branches: [main]
+
+  workflow_dispatch:
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v3
+        with:
+          args: 'format --check --diff'

CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+# [0.20.0] - 2025-07-14
+
+### Added
+
+-   text command group, see [Text](https://github.com/onyx-and-iris/obsws-cli?tab=readme-ov-file#text)
+
+# [0.19.0] - 2025-06-23
+
+### Added
+
+-   record split and record chapter commands, see [Record](https://github.com/onyx-and-iris/obsws-cli?tab=readme-ov-file#record)
+    -   As of OBS 30.2.0, the only file format supporting *record chapter* is Hybrid MP4.
+
+# [0.18.0] - 2025-06-21
+
+### Added
+
+-   Various colouring styles, see [Style](https://github.com/onyx-and-iris/obsws-cli/tree/main?tab=readme-ov-file#style)
+    -   colouring is applied to list tables as well as highlighted information in stdout/stderr output.
+    -   table border styling may be optionally disabled with the --no-border flag.
+
+
 # [0.17.3] - 2025-06-20
 
 ### Added

README.md

@@ -14,6 +14,7 @@ For an outline of past/future changes refer to: [CHANGELOG](CHANGELOG.md)
 
 - [Installation](#installation)
 - [Configuration](#configuration)
+- [Style](#style)
 - [Commands](#root-typer)
 - [License](#license)
 
@@ -68,6 +69,37 @@ OBS_PASSWORD=<websocket password>
 
 Flags can be used to override environment variables.
 
+## Style
+
+Styling is opt-in, by default you will get a colourless output:
+
+![colourless](./img/colourless.png)
+
+You may enable styling with the --style/-s flag:
+
+```console
+obsws-cli --style="cyan" sceneitem list
+```
+
+Available styles: _red, magenta, purple, blue, cyan, green, yellow, orange, white, grey, navy, black_
+
+![coloured](./img/coloured-border.png)
+
+Optionally you may disable border colouring with the --no-border flag:
+
+![coloured-no-border](./img/coloured-no-border.png)
+
+```console
+obsws-cli --style="cyan" --no-border sceneitem list
+```
+
+Or with environment variables:
+
+```env
+OBS_STYLE=cyan
+OBS_STYLE_NO_BORDER=true
+```
+
 ## Root Typer
 
 -   obs-version: Get the OBS Client and WebSocket versions.
@@ -303,6 +335,22 @@ obsws-cli input unmute "Mic/Aux"
 obsws-cli input toggle "Mic/Aux"
 ```
 
+#### Text
+
+-   current: Get the current text for a text input.
+    -   args: <input_name>
+
+```console
+obsws-cli text current "My Text Input"
+```
+
+-   update: Update the text of a text input.
+    -   args: <input_name> <new_text>
+
+```console
+obsws-cli text update "My Text Input" "hi OBS!"
+```
+
 #### Record
 
 -   start: Start recording.
@@ -354,6 +402,21 @@ obsws-cli record directory "/home/me/obs-vids/"
 obsws-cli record directory "C:/Users/me/Videos"
 ```
 
+-   split: Split the current recording.
+
+```console
+obsws-cli record split
+```
+
+-   chapter: Create a chapter in the current recording.
+
+    *optional*
+    -   args: <chapter_name>
+
+```console
+obsws-cli record chapter "Chapter Name"
+```
+
 #### Stream
 
 -   start: Start streaming.
@@ -613,34 +676,6 @@ obsws-cli projector open --monitor-index=1 "test_group"
 obsws-cli screenshot save --width=2560 --height=1440 "Scene" "C:\Users\me\Videos\screenshot.png"
 ```
 
-## Style
-
-By default styling is disabled but you may enable it with:
-
--   --style/-s: Style used in output.
-    -  OBS_STYLE
--   --no-border/-b: Disable table border styling in output.
-    -  OBS_STYLE_NO_BORDER
-
-Available styles:
-
-- red
-- magenta
-- purple
-- blue
-- cyan
-- green
-- yellow
-- orange
-- white
-- grey
-- navy
-- black
-
-```console
-obsws-cli --style=cyan --no-border scene list
-```
-
 ## License
 
 `obsws-cli` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

obsws_cli/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present onyx-and-iris <code@onyxandiris.online>
 #
 # SPDX-License-Identifier: MIT
-__version__ = "0.17.6"
+__version__ = '0.20.1'

obsws_cli/__init__.py

@@ -4,4 +4,4 @@
 
 from .app import app
 
-__all__ = ["app"]
+__all__ = ['app']

obsws_cli/alias.py

@@ -44,6 +44,8 @@ class RootTyperAliasGroup(typer.core.TyperGroup):
                 cmd_name = 'stream'
             case 'sm':
                 cmd_name = 'studiomode'
+            case 't':
+                cmd_name = 'text'
             case 'vc':
                 cmd_name = 'virtualcam'
         return super().get_command(ctx, cmd_name)

obsws_cli/app.py

@@ -7,7 +7,7 @@ from typing import Annotated
 import obsws_python as obsws
 import typer
 
-from obsws_cli.__about__ import __version__ as obsws_cli_version
+from obsws_cli.__about__ import __version__ as version
 
 from . import console, settings, styles
 from .alias import RootTyperAliasGroup
@@ -28,6 +28,7 @@ for sub_typer in (
     'screenshot',
     'stream',
     'studiomode',
+    'text',
     'virtualcam',
 ):
     module = importlib.import_module(f'.{sub_typer}', package=__package__)
@@ -37,7 +38,7 @@ for sub_typer in (
 def version_callback(value: bool):
     """Show the version of the CLI."""
     if value:
-        console.out.print(f'obsws-cli version: {obsws_cli_version}')
+        console.out.print(f'obsws-cli version: {version}')
         raise typer.Exit()
 
 
@@ -50,6 +51,15 @@ def setup_logging(debug: bool):
     )
 
 
+def validate_style(value: str):
+    """Validate and return the style."""
+    if value not in styles.registry:
+        raise typer.BadParameter(
+            f'Invalid style: {value}. Available styles: {", ".join(styles.registry.keys())}'
+        )
+    return value
+
+
 @app.callback()
 def main(
     ctx: typer.Context,
@@ -112,6 +122,7 @@ def main(
             envvar='OBS_STYLE',
             help='Set the style for the CLI output',
             show_default='disabled',
+            callback=validate_style,
         ),
     ] = settings.get('style'),
     no_border: Annotated[

obsws_cli/filter.py

@@ -62,8 +62,8 @@ def list_(
         (Text('Enabled', justify='center'), 'center', None),
         (Text('Settings', justify='center'), 'center', ctx.obj['style'].column),
     ]
-    for name, justify, style in columns:
+    for heading, justify, style in columns:
-        table.add_column(name, justify=justify, style=style)
+        table.add_column(heading, justify=justify, style=style)
 
     for filter in resp.filters:
         resp = ctx.obj['obsws'].get_source_filter_default_settings(filter['filterKind'])

obsws_cli/group.py

@@ -61,8 +61,8 @@ def list_(
         (Text('Group Name', justify='center'), 'left', ctx.obj['style'].column),
         (Text('Enabled', justify='center'), 'center', None),
     ]
-    for column, justify, style in columns:
+    for heading, justify, style in columns:
-        table.add_column(column, justify=justify, style=style)
+        table.add_column(heading, justify=justify, style=style)
 
     for item_id, group_name, is_enabled in groups:
         table.add_row(

obsws_cli/input.py

@@ -74,8 +74,8 @@ def list_(
             (Text('Kind', justify='center'), 'center', ctx.obj['style'].column),
             (Text('Muted', justify='center'), 'center', None),
         ]
-    for column, justify, style in columns:
+    for heading, justify, style in columns:
-        table.add_column(column, justify=justify, style=style)
+        table.add_column(heading, justify=justify, style=style)
 
     for input_name, input_kind, input_uuid in inputs:
         input_mark = ''

obsws_cli/profile.py

@@ -29,13 +29,15 @@ def list_(ctx: typer.Context):
         (Text('Profile Name', justify='center'), 'left', ctx.obj['style'].column),
         (Text('Current', justify='center'), 'center', None),
     ]
-    for column, justify, style in columns:
+    for heading, justify, style in columns:
-        table.add_column(column, justify=justify, style=style)
+        table.add_column(heading, justify=justify, style=style)
 
     for profile in resp.profiles:
         table.add_row(
             profile,
-            util.check_mark(profile == resp.current_profile_name, empty_if_false=True),
+            util.check_mark(
+                ctx, profile == resp.current_profile_name, empty_if_false=True
+            ),
         )
 
     console.out.print(table)

obsws_cli/record.py

@@ -130,3 +130,43 @@ def directory(
         console.out.print(
             f'Recording directory: {console.highlight(ctx, resp.record_directory)}'
         )
+
+
+@app.command('split | sp')
+def split(ctx: typer.Context):
+    """Split the current recording."""
+    active, paused = _get_recording_status(ctx)
+    if not active:
+        console.err.print('Recording is not in progress, cannot split.')
+        raise typer.Exit(1)
+    if paused:
+        console.err.print('Recording is paused, cannot split.')
+        raise typer.Exit(1)
+
+    ctx.obj['obsws'].split_record_file()
+    console.out.print('Recording split successfully.')
+
+
+@app.command('chapter | ch')
+def chapter(
+    ctx: typer.Context,
+    chapter_name: Annotated[
+        Optional[str],
+        typer.Argument(
+            help='Name of the chapter to create.',
+        ),
+    ] = None,
+):
+    """Create a chapter in the current recording."""
+    active, paused = _get_recording_status(ctx)
+    if not active:
+        console.err.print('Recording is not in progress, cannot create chapter.')
+        raise typer.Exit(1)
+    if paused:
+        console.err.print('Recording is paused, cannot create chapter.')
+        raise typer.Exit(1)
+
+    ctx.obj['obsws'].create_record_chapter(chapter_name)
+    console.out.print(
+        f'Chapter {console.highlight(ctx, chapter_name or "unnamed")} created successfully.'
+    )

obsws_cli/scene.py

@@ -43,8 +43,8 @@ def list_(
             (Text('Scene Name', justify='center'), 'left', ctx.obj['style'].column),
             (Text('Active', justify='center'), 'center', None),
         ]
-    for column, justify, style in columns:
+    for heading, justify, style in columns:
-        table.add_column(column, justify=justify, style=style)
+        table.add_column(heading, justify=justify, style=style)
 
     for scene_name, scene_uuid in scenes:
         if uuid:
@@ -108,7 +108,11 @@ def switch(
 
     if preview:
         ctx.obj['obsws'].set_current_preview_scene(scene_name)
-        console.out.print(f'Switched to preview scene: [green]{scene_name}[/green]')
+        console.out.print(
+            f'Switched to preview scene: {console.highlight(ctx, scene_name)}'
+        )
     else:
         ctx.obj['obsws'].set_current_program_scene(scene_name)
-        console.out.print(f'Switched to program scene: [green]{scene_name}[/green]')
+        console.out.print(
+            f'Switched to program scene: {console.highlight(ctx, scene_name)}'
+        )

obsws_cli/sceneitem.py

@@ -78,8 +78,8 @@ def list_(
             ('Enabled', 'center', None),
         ]
     # Add columns to the table
-    for column, justify, style in columns:
+    for heading, justify, style in columns:
-        table.add_column(column, justify=justify, style=style)
+        table.add_column(heading, justify=justify, style=style)
 
     for item_id, item_name, is_group, is_enabled, source_uuid in items:
         if is_group:

obsws_cli/settings.py

@@ -16,6 +16,7 @@ class Settings(UserDict):
     The settings are expected to be in uppercase and should start with 'OBS_'.
 
     Example:
+    -------
         settings = Settings()
         host = settings['OBS_HOST']
         settings['OBS_PORT'] = 4455
@@ -64,12 +65,15 @@ def get(key: str) -> SettingsValue:
     """Get a setting value by key.
 
     Args:
+    ----
         key (str): The key of the setting to retrieve.
 
     Returns:
+    -------
         The value of the setting.
 
     Raises:
+    ------
         KeyError: If the key does not exist in the settings.
 
     """

obsws_cli/styles.py

@@ -3,15 +3,15 @@
 import os
 from dataclasses import dataclass
 
-_registry = {}
+registry = {}
 
 
 def register_style(cls):
     """Register a style class."""
     key = cls.__name__.lower()
-    if key in _registry:
+    if key in registry:
         raise ValueError(f'Style {key} is already registered.')
-    _registry[key] = cls
+    registry[key] = cls
     return cls
 
 
@@ -19,11 +19,10 @@ def register_style(cls):
 class Style:
     """Base class for styles."""
 
-    name: str = 'no_colour'
+    name: str
-    description: str = 'Style disabled'
+    border: str
-    border: str | None = None
+    column: str
-    column: str | None = None
+    highlight: str
-    highlight: str | None = None
     no_border: bool = False
 
     def __post_init__(self):
@@ -32,9 +31,16 @@ class Style:
         if self.no_border:
             self.border = None
 
-    def __str__(self):
+
-        """Return a string representation of the style."""
+@register_style
-        return f'{self.name} - {self.description}'
+@dataclass
+class Disabled(Style):
+    """Disabled style."""
+
+    name: str = 'disabled'
+    border: str = 'none'
+    column: str = 'none'
+    highlight: str = 'none'
 
 
 @register_style
@@ -43,10 +49,9 @@ class Red(Style):
     """Red style."""
 
     name: str = 'red'
-    description: str = 'Red text color'
     border: str = 'red3'
-    highlight: str = 'red1'
     column: str = 'red1'
+    highlight: str = 'red1'
 
 
 @register_style
@@ -55,10 +60,9 @@ class Magenta(Style):
     """Magenta style."""
 
     name: str = 'magenta'
-    description: str = 'Magenta text color'
     border: str = 'magenta3'
-    highlight: str = 'orchid1'
     column: str = 'orchid1'
+    highlight: str = 'orchid1'
 
 
 @register_style
@@ -67,10 +71,9 @@ class Purple(Style):
     """Purple style."""
 
     name: str = 'purple'
-    description: str = 'Purple text color'
     border: str = 'medium_purple4'
-    highlight: str = 'medium_purple'
     column: str = 'medium_purple'
+    highlight: str = 'medium_purple'
 
 
 @register_style
@@ -79,10 +82,9 @@ class Blue(Style):
     """Blue style."""
 
     name: str = 'blue'
-    description: str = 'Blue text color'
     border: str = 'cornflower_blue'
-    highlight: str = 'sky_blue2'
     column: str = 'sky_blue2'
+    highlight: str = 'sky_blue2'
 
 
 @register_style
@@ -91,10 +93,9 @@ class Cyan(Style):
     """Cyan style."""
 
     name: str = 'cyan'
-    description: str = 'Cyan text color'
     border: str = 'dark_cyan'
-    highlight: str = 'cyan'
     column: str = 'cyan'
+    highlight: str = 'cyan'
 
 
 @register_style
@@ -103,10 +104,9 @@ class Green(Style):
     """Green style."""
 
     name: str = 'green'
-    description: str = 'Green text color'
     border: str = 'green4'
-    highlight: str = 'spring_green3'
     column: str = 'spring_green3'
+    highlight: str = 'spring_green3'
 
 
 @register_style
@@ -115,10 +115,9 @@ class Yellow(Style):
     """Yellow style."""
 
     name: str = 'yellow'
-    description: str = 'Yellow text color'
     border: str = 'yellow3'
-    highlight: str = 'wheat1'
     column: str = 'wheat1'
+    highlight: str = 'wheat1'
 
 
 @register_style
@@ -127,10 +126,9 @@ class Orange(Style):
     """Orange style."""
 
     name: str = 'orange'
-    description: str = 'Orange text color'
     border: str = 'dark_orange'
-    highlight: str = 'orange1'
     column: str = 'orange1'
+    highlight: str = 'orange1'
 
 
 @register_style
@@ -139,10 +137,9 @@ class White(Style):
     """White style."""
 
     name: str = 'white'
-    description: str = 'White text color'
     border: str = 'grey82'
-    highlight: str = 'grey100'
     column: str = 'grey100'
+    highlight: str = 'grey100'
 
 
 @register_style
@@ -151,10 +148,9 @@ class Grey(Style):
     """Grey style."""
 
     name: str = 'grey'
-    description: str = 'Grey text color'
     border: str = 'grey50'
-    highlight: str = 'grey70'
     column: str = 'grey70'
+    highlight: str = 'grey70'
 
 
 @register_style
@@ -163,10 +159,9 @@ class Navy(Style):
     """Navy Blue style."""
 
     name: str = 'navyblue'
-    description: str = 'Navy Blue text color'
     border: str = 'deep_sky_blue4'
-    highlight: str = 'light_sky_blue3'
     column: str = 'light_sky_blue3'
+    highlight: str = 'light_sky_blue3'
 
 
 @register_style
@@ -175,17 +170,14 @@ class Black(Style):
     """Black style."""
 
     name: str = 'black'
-    description: str = 'Black text color'
     border: str = 'grey19'
     column: str = 'grey11'
+    highlight: str = 'grey11'
 
 
 def request_style_obj(style_name: str, no_border: bool) -> Style:
     """Entry point for style objects. Returns a Style object based on the style name."""
-    style_name = str(style_name).lower()  # coerce the type to string and lowercase it
+    if style_name == 'disabled':
+        os.environ['NO_COLOR'] = '1'
 
-    if style_name not in _registry:
+    return registry[style_name.lower()](no_border=no_border)
-        os.environ['NO_COLOR'] = '1'  # Disable colour output
-        return Style()
-
-    return _registry[style_name](no_border=no_border)

obsws_cli/text.py

@@ -0,0 +1,78 @@
+"""module containing commands for manipulating text inputs."""
+
+from typing import Annotated, Optional
+
+import typer
+
+from . import console, validate
+from .alias import SubTyperAliasGroup
+
+app = typer.Typer(cls=SubTyperAliasGroup)
+
+
+@app.callback()
+def main():
+    """Control text inputs in OBS."""
+
+
+@app.command('current | get')
+def current(
+    ctx: typer.Context,
+    input_name: Annotated[str, typer.Argument(help='Name of the text input to get.')],
+):
+    """Get the current text for a text input."""
+    if not validate.input_in_inputs(ctx, input_name):
+        console.err.print(f'Input [yellow]{input_name}[/yellow] not found.')
+        raise typer.Exit(1)
+
+    resp = ctx.obj['obsws'].get_input_settings(name=input_name)
+    if not resp.input_kind.startswith('text_'):
+        console.err.print(
+            f'Input [yellow]{input_name}[/yellow] is not a text input.',
+        )
+        raise typer.Exit(1)
+
+    current_text = resp.input_settings.get('text', '')
+    if not current_text:
+        current_text = '(empty)'
+    console.out.print(
+        f'Current text for input {console.highlight(ctx, input_name)}: {current_text}',
+    )
+
+
+@app.command('update | set')
+def update(
+    ctx: typer.Context,
+    input_name: Annotated[
+        str, typer.Argument(help='Name of the text input to update.')
+    ],
+    new_text: Annotated[
+        Optional[str],
+        typer.Argument(
+            help='The new text to set for the input.',
+        ),
+    ] = None,
+):
+    """Update the text of a text input."""
+    if not validate.input_in_inputs(ctx, input_name):
+        console.err.print(f'Input [yellow]{input_name}[/yellow] not found.')
+        raise typer.Exit(1)
+
+    resp = ctx.obj['obsws'].get_input_settings(name=input_name)
+    if not resp.input_kind.startswith('text_'):
+        console.err.print(
+            f'Input [yellow]{input_name}[/yellow] is not a text input.',
+        )
+        raise typer.Exit(1)
+
+    ctx.obj['obsws'].set_input_settings(
+        name=input_name,
+        settings={'text': new_text},
+        overlay=True,
+    )
+
+    if not new_text:
+        new_text = '(empty)'
+    console.out.print(
+        f'Text for input {console.highlight(ctx, input_name)} updated to: {new_text}',
+    )

obsws_cli/util.py

@@ -13,6 +13,10 @@ def check_mark(value: bool, empty_if_false: bool = False) -> str:
     if empty_if_false and not value:
         return ''
 
+    # rich gracefully handles the absence of colour throughout the rest of the application,
+    # but here we must handle it manually.
+    # If NO_COLOR is set, we return plain text symbols.
+    # Otherwise, we return coloured symbols.
     if os.getenv('NO_COLOR', '') != '':
         return '✓' if value else '✗'
     return '✅' if value else '❌'

pyproject.toml

@@ -21,7 +21,7 @@ classifiers = [
   "Programming Language :: Python :: Implementation :: CPython",
   "Programming Language :: Python :: Implementation :: PyPy",
 ]
-dependencies = ["typer>=0.16.0", "obsws-python>=1.7.2", "python-dotenv>=1.1.0"]
+dependencies = ["typer>=0.16.0", "obsws-python>=1.8.0", "python-dotenv>=1.1.0"]
 
 
 [project.urls]

tests/conftest.py

@@ -71,6 +71,13 @@ def pytest_sessionstart(session):
         },
         sceneItemEnabled=True,
     )
+    session.obsws.create_input(
+        sceneName='pytest_scene',
+        inputName='pytest_text_input',
+        inputKind='text_gdiplus_v3',
+        inputSettings={'text': 'Hello, OBS!'},
+        sceneItemEnabled=True,
+    )
     resp = session.obsws.get_scene_item_list('pytest_scene')
     for item in resp.scene_items:
         if item['sourceName'] == 'pytest_input_2':

tests/test_text.py

@@ -0,0 +1,18 @@
+"""Unit tests for the text command in the OBS WebSocket CLI."""
+
+from typer.testing import CliRunner
+
+from obsws_cli.app import app
+
+runner = CliRunner(mix_stderr=False)
+
+
+def test_text_update():
+    """Test the text update command."""
+    result = runner.invoke(app, ['text', 'current', 'pytest_text_input'])
+    assert result.exit_code == 0
+    assert 'Current text for input pytest_text_input: Hello, OBS!' in result.stdout
+
+    result = runner.invoke(app, ['text', 'update', 'pytest_text_input', 'New Text'])
+    assert result.exit_code == 0
+    assert 'Text for input pytest_text_input updated to: New Text' in result.stdout