CLI utilities - tmuxp.cli.utils

CLI utility helpers for tmuxp.

class tmuxp.cli.utils.ColorMode(*values)[source]

Bases: Enum

Color output modes for CLI.

Examples

>>> ColorMode.AUTO.value
'auto'
>>> ColorMode.ALWAYS.value
'always'
>>> ColorMode.NEVER.value
'never'
AUTO = 'auto'
ALWAYS = 'always'
NEVER = 'never'
class tmuxp.cli.utils.Colors(mode=ColorMode.AUTO)[source]

Bases: object

Semantic color utilities for CLI output.

Provides semantic color methods (success, warning, error, etc.) that conditionally apply ANSI colors based on the color mode and environment.

Parameters:

mode (ColorMode) – Color mode to use. Default is AUTO which detects TTY.

SUCCESS

Color name for success messages (green)

Type:

str

WARNING

Color name for warning messages (yellow)

Type:

str

ERROR

Color name for error messages (red)

Type:

str

INFO

Color name for informational messages (cyan)

Type:

str

HEADING

Color name for section headers (bright_cyan)

Type:

str

HIGHLIGHT

Color name for highlighted/important text (magenta)

Type:

str

MUTED

Color name for subdued/secondary text (blue)

Type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.success("session loaded")
'session loaded'
>>> colors.error("failed to load")
'failed to load'

>>> colors = Colors(ColorMode.ALWAYS)
>>> result = colors.success("ok")

Check that result contains ANSI escape codes:

>>> "\033[" in result
True
ERROR = 'red'
HEADING = 'bright_cyan'
HIGHLIGHT = 'magenta'
INFO = 'cyan'
MUTED = 'blue'
SUCCESS = 'green'
WARNING = 'yellow'
_colorize(text, fg, bold=False, dim=False)[source]

Apply color using style() function.

Return type:

str

Parameters:

  • text (str) – Text to colorize.

  • fg (str) – Foreground color name (e.g., “green”, “red”).

  • bold (bool) – Whether to apply bold style. Default is False.

  • dim (bool) – Whether to apply dim/faint style. Default is False.

Returns:

Colorized text if enabled, plain text otherwise.

Return type:

str

Examples

When colors are enabled, applies ANSI escape codes:

>>> colors = Colors(ColorMode.ALWAYS)
>>> colors._colorize("test", "green")
'...'

When colors are disabled, returns plain text:

>>> colors = Colors(ColorMode.NEVER)
>>> colors._colorize("test", "green")
'test'
_should_enable()[source]

Determine if color should be enabled.

Follows CPython-style precedence: 1. NO_COLOR env var (any value) -> disable 2. ColorMode.NEVER -> disable 3. ColorMode.ALWAYS -> enable 4. FORCE_COLOR env var (any value) -> enable 5. TTY check -> enable if stdout is a terminal

Return type:

bool

Returns:

True if colors should be enabled.

Return type:

bool

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors._should_enable()
False
error(text, bold=False)[source]

Format text as error (red).

Return type:

str

Parameters:

  • text (str) – Text to format.

  • bold (bool) – Whether to apply bold style. Default is False.

Returns:

Formatted text.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.error("failed")
'failed'
format_kv(key, value)[source]

Format key: value pair with syntax highlighting.

Return type:

str

Parameters:

  • key (str) – Key/label to highlight.

  • value (str) – Value to display (not colorized, allows caller to format).

Returns:

Formatted “key: value” string with highlighted key.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.format_kv("tmux version", "3.2a")
'tmux version: 3.2a'
format_label(label)[source]

Format a label (key in key:value pair).

Return type:

str

Parameters:

label (str) – Label text to format.

Returns:

Highlighted label text (bold magenta when colors enabled).

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.format_label("tmux path")
'tmux path'
format_path(path)[source]

Format a file path with info color.

Return type:

str

Parameters:

path (str) – Path string to format.

Returns:

Cyan-colored path when colors enabled.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.format_path("/usr/bin/tmux")
'/usr/bin/tmux'
format_separator(length=25)[source]

Format a visual separator line.

Return type:

str

Parameters:

length (int) – Length of the separator line. Default is 25.

Returns:

Muted (blue) separator line when colors enabled.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.format_separator()
'-------------------------'
>>> colors.format_separator(10)
'----------'
format_tmux_option(line)[source]

Format tmux option line with syntax highlighting.

Handles tmux show-options output formats: - “key value” (space-separated) - “key=value” (equals-separated) - “key[index] value” (array-indexed options) - “key” (empty array options with no value)

Return type:

str

Parameters:

line (str) – Option line to format.

Returns:

Formatted line with highlighted key and info-colored value.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.format_tmux_option("status on")
'status on'
>>> colors.format_tmux_option("base-index=1")
'base-index=1'
>>> colors.format_tmux_option("pane-colours")
'pane-colours'
>>> colors.format_tmux_option('status-format[0] "#[align=left]"')
'status-format[0] "#[align=left]"'
format_version(version)[source]

Format a version string.

Return type:

str

Parameters:

version (str) – Version string to format.

Returns:

Cyan-colored version when colors enabled.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.format_version("3.2a")
'3.2a'
heading(text)[source]

Format text as a section heading (bright cyan, bold).

Used for section headers like ‘Local workspaces:’ or ‘Global workspaces:’. Uses bright_cyan to visually distinguish from info() which uses cyan.

Return type:

str

Parameters:

text (str) – Text to format.

Returns:

Formatted text.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.heading("Local workspaces:")
'Local workspaces:'
highlight(text, bold=True)[source]

Format text as highlighted (magenta, bold by default).

Return type:

str

Parameters:

  • text (str) – Text to format.

  • bold (bool) – Whether to apply bold style. Default is True.

Returns:

Formatted text.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.highlight("my-session")
'my-session'
info(text, bold=False)[source]

Format text as info (cyan).

Return type:

str

Parameters:

  • text (str) – Text to format.

  • bold (bool) – Whether to apply bold style. Default is False.

Returns:

Formatted text.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.info("/path/to/config.yaml")
'/path/to/config.yaml'
muted(text)[source]

Format text as muted (blue).

Return type:

str

Parameters:

text (str) – Text to format.

Returns:

Formatted text.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.muted("(optional)")
'(optional)'
success(text, bold=False)[source]

Format text as success (green).

Return type:

str

Parameters:

  • text (str) – Text to format.

  • bold (bool) – Whether to apply bold style. Default is False.

Returns:

Formatted text.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.success("loaded")
'loaded'
warning(text, bold=False)[source]

Format text as warning (yellow).

Return type:

str

Parameters:

  • text (str) – Text to format.

  • bold (bool) – Whether to apply bold style. Default is False.

Returns:

Formatted text.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.warning("check config")
'check config'
exception tmuxp.cli.utils.UnknownStyleColor(color, *args, **kwargs)[source]

Bases: Exception

Raised when encountering an unknown terminal style color.

Examples

>>> try:
...     raise UnknownStyleColor("invalid_color")
... except UnknownStyleColor as e:
...     "invalid_color" in str(e)
True
tmuxp.cli.utils.prompt(name, default=None, value_proc=None, *, color_mode=None)[source]

Return user input from command line.

Return type:

str

Parameters:

  • name – prompt text

  • default – default value if no input provided.

  • color_mode – color mode for prompt styling. Defaults to AUTO if not specified.

Return type:

str

See also

prompt(), prompt_bool() and prompt_choices() are from flask-script. See the flask-script license.

tmuxp.cli.utils.prompt_bool(name, default=False, yes_choices=None, no_choices=None, *, color_mode=None)[source]

Return True / False by prompting user input from command line.

Return type:

bool

Parameters:

  • name – prompt text

  • default – default value if no input provided.

  • yes_choices – default ‘y’, ‘yes’, ‘1’, ‘on’, ‘true’, ‘t’

  • no_choices – default ‘n’, ‘no’, ‘0’, ‘off’, ‘false’, ‘f’

  • color_mode – color mode for prompt styling. Defaults to AUTO if not specified.

Return type:

bool

tmuxp.cli.utils.prompt_choices(name, choices, default=None, no_choice=('none',), *, color_mode=None)[source]

Return user input from command line from set of provided choices.

Return type:

str | None

Parameters:

  • name – prompt text

  • choices – Sequence of available choices. Each choice may be a single string or a (key, value) tuple where key is used for matching.

  • default – default value if no input provided.

  • no_choice – acceptable list of strings for “null choice”

  • color_mode – color mode for prompt styling. Defaults to AUTO if not specified.

Return type:

str

tmuxp.cli.utils.prompt_yes_no(name, default=True, *, color_mode=None)[source]

prompt_bool() returning yes by default.

Return type:

bool

Parameters:

  • name – prompt text

  • default – default value if no input provided.

  • color_mode – color mode for prompt styling. Defaults to AUTO if not specified.

tmuxp.cli.utils.strip_ansi(value)[source]

Clear ANSI escape codes from a string value.

Return type:

str

Parameters:

value (str) – String potentially containing ANSI escape codes.

Returns:

String with ANSI codes removed.

Return type:

str

Examples

>>> strip_ansi("\033[32mgreen\033[0m")
'green'
>>> strip_ansi("plain text")
'plain text'
tmuxp.cli.utils.style(text, fg=None, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, reset=True)[source]

Apply ANSI styling to text.

Credit: click.

Return type:

str

Parameters:

  • text (Any) – Text to style (will be converted to str).

  • fg (CLIColour | None) – Foreground color (name, 256-index, or RGB tuple).

  • bg (CLIColour | None) – Background color.

  • bold (bool | None) – Apply bold style.

  • dim (bool | None) – Apply dim style.

  • underline (bool | None) – Apply underline style.

  • overline (bool | None) – Apply overline style.

  • italic (bool | None) – Apply italic style.

  • blink (bool | None) – Apply blink style.

  • reverse (bool | None) – Apply reverse video style.

  • strikethrough (bool | None) – Apply strikethrough style.

  • reset (bool) – Append reset code at end. Default True.

Returns:

Styled text with ANSI escape codes.

Return type:

str

Examples

>>> style("hello", fg="green")
'\x1b[32m...'
>>> "hello" in style("hello", fg="green")
True
tmuxp.cli.utils.tmuxp_echo(message=None, log_level='INFO', style_log=False)[source]

Combine logging.log and print for CLI output.

Return type:

None

Parameters:

  • message (str | None) – Message to log and print. If None, does nothing.

  • log_level (str) – Log level to use (DEBUG, INFO, WARNING, ERROR, CRITICAL). Default is INFO.

  • style_log (bool) – If True, preserve ANSI styling in log output. If False, strip ANSI codes from log output. Default is False.

Examples

>>> tmuxp_echo("Session loaded")
Session loaded

>>> tmuxp_echo("Warning message", log_level="WARNING")
Warning message
tmuxp.cli.utils.unstyle(text)[source]

Remove ANSI styling information from a string.

Usually it’s not necessary to use this function as tmuxp_echo function will automatically remove styling if necessary.

Credit: click.

Return type:

str

Parameters:

text (str) – Text to remove style information from.

Returns:

Text with ANSI codes removed.

Return type:

str

Examples

>>> unstyle("\033[32mgreen\033[0m")
'green'