CLI Reference

Complete command-line interface reference for TUIOS.

Every command below accepts --help, which is authoritative. This page documents what the binary actually does, including the places where the flags and the runtime options disagree.

Installation

See Getting Started for installation instructions.

Basic Usage

tuios [flags]
tuios [command] [flags]

Global Flags

These are registered as persistent flags on the root command, so they are accepted by every subcommand. Most of them only mean something to a command that draws a TUI (tuios, tuios attach, tuios new, tuios tape play). Passing --theme to tuios ls is accepted and ignored.

--theme

Set the color theme.

tuios --theme dracula
tuios --theme nord
tuios --theme tokyonight

The default is empty, not a named theme. With no --theme and no theme in the config file, TUIOS uses your terminal's own 16 ANSI colors rather than overriding them.

--list-themes

List all available themes (300+).

tuios --list-themes

--preview-theme

Preview a theme's colors.

tuios --preview-theme dracula

Combine with fzf for interactive selection:

tuios --theme $(tuios --list-themes | fzf --preview 'tuios --preview-theme {}')

--debug

Enable debug logging.

tuios --debug

--ascii-only

Use ASCII characters instead of Nerd Font icons.

tuios --ascii-only

--show-keys

Show pressed keys overlay (for demos and recordings).

tuios --show-keys

--border-style

Set window border style.

Values: rounded, normal, thick, double, hidden, block, ascii, outer-half-block, inner-half-block

tuios --border-style thick
tuios --border-style hidden

--dockbar-position

Set dockbar position.

Values: bottom, top, hidden

tuios --dockbar-position top
tuios --dockbar-position hidden

--hide-window-buttons

Hide window control buttons.

tuios --hide-window-buttons

--scrollback-lines

Set scrollback buffer size (100-1000000).

tuios --scrollback-lines 20000

--no-animations

Disable window animations for instant transitions.

tuios --no-animations

When enabled, windows will instantly snap to their positions without animated transitions. Useful for lower-end hardware or users who prefer instant feedback.

--confirm-quit

Always show the quit confirmation dialog, even when no foreground processes are running.

tuios --confirm-quit

By default, TUIOS only shows the confirmation dialog if there are active foreground processes that would be killed on exit. This flag makes it always ask before quitting.

--window-title-position

Set window title position.

Values: bottom, top, hidden

tuios --window-title-position top
tuios --window-title-position hidden

When set to hidden, window titles are not displayed and the rename keybinding (r) is disabled.

--hide-clock

Hide the clock overlay. Deprecated: the clock is hidden by default, so this flag is a no-op kept for compatibility. Use --show-clock to opt in instead.

tuios --hide-clock

The clock still appears during tape recording (red background) or when prefix mode is active.

--show-clock

Show the clock overlay.

tuios --show-clock

--show-cpu

Show CPU usage indicator in the dockbar.

tuios --show-cpu

--show-ram

Show RAM usage indicator in the dockbar.

tuios --show-ram

--shared-borders

Enable shared borders between adjacent tiled windows for a more compact layout.

tuios --shared-borders

--hide-scrollbar

Hide the scrollbar thumb drawn on the window border.

tuios --hide-scrollbar

--zoom-max-width

Cap the width, in cells, that zoom mode expands a window to. 0 means fullscreen.

tuios --zoom-max-width 120

Useful on ultrawide displays where a fullscreen zoom produces unreadably long lines.

--cpuprofile

Write a CPU profile to a file, for development.

tuios --cpuprofile cpu.prof

--pprof

Serve net/http/pprof on the given address for live profiling.

tuios --pprof localhost:6060

-v, --version

Print the version, commit, build date, and builder, then exit.

tuios --version

There is no tuios version subcommand. tuios version is an error.

Commands

Several commands have aliases:

Daemon Mode (Session Persistence)

TUIOS supports persistent sessions that continue running in the background, similar to tmux or screen.

new

Create a new persistent session and attach to it. Alias: n.

tuios new [session-name] [flags]

Flags:

• -d, --detach - Create the session headless, without attaching a client

Examples:

# Create session with auto-generated name
tuios new

# Create named session
tuios new mysession

# Create session with theme
tuios new work --theme dracula

# Create a headless session for scripting
tuios new build --detach

A --detach session gets an initial window and is immediately usable by send-keys, run-command, and capture-pane. It is created at a fixed 80x24 until a client attaches, and the appearance flags are ignored because there is no client to apply them to. See Headless Sessions.

attach

Attach to an existing session. Alias: a.

tuios attach [session-name] [flags]

Flags:

• -c, --create - Create session if it doesn't exist

Examples:

# Attach to most recent session
tuios attach

# Attach to named session
tuios attach mysession

# Attach or create if doesn't exist
tuios attach mysession -c

ls

List all TUIOS sessions. Alias: list-sessions.

tuios ls [flags]

Flags:

• --json - Output as JSON

Without --json it prints a table of session name, window count, status, creation time, and last activity.

JSON output is a bare array, with no wrapper object:

[
  {
    "name": "work",
    "id": "7f55590c-ecc0-450e-88a3-3cb1ff2573c8",
    "created": 1784391188,
    "last_active": 1784391188,
    "window_count": 3,
    "attached": false,
    "width": 120,
    "height": 40
  }
]

created and last_active are Unix seconds.

resurrect

Restore a session saved to disk after the daemon exited. Alias: restore.

tuios resurrect [session-name]

With no argument it lists the sessions that can be restored. With a name it restores that session and attaches to it.

Resurrection restores window structure, not running processes or scrollback. See Session Resurrection for exactly what survives.

kill-session

Kill a specific session.

tuios kill-session <session-name>

kill-server

Stop the TUIOS daemon.

tuios kill-server

daemon

Run the daemon in the foreground, for debugging.

tuios daemon [flags]

Flags:

• --log-level <level> - Debug log level: off, errors, basic, messages, verbose, trace
• --no-restore - Do not auto-restore saved sessions on start

# Watch every protocol message go by
tuios daemon --log-level messages

# Start clean, ignoring saved session state
tuios daemon --no-restore

start-server

Start the daemon in the background.

tuios start-server

logs

View the daemon's logs.

tuios logs [flags]

Flags:

• -n, --lines <n> - Number of entries to show, default 50. 0 means all
• --all - Show all stored log entries
• -f, --follow - Keep printing new entries as they arrive
• --clear - Clear the logs after viewing

# Last 50 entries
tuios logs

# Last 200
tuios logs -n 200

# Tail the log
tuios logs -f

The amount of detail in the log depends on the --log-level the daemon was started with.

layout

Manage layout templates (saved window arrangements).

layout list

List all saved layout templates.

tuios layout list

layout delete

Delete a saved layout template.

tuios layout delete <name>

layout dir

Show the layout templates directory path.

tuios layout dir

layout export

Export a layout template as a tape script, printed to stdout. The name is required and is the only argument; there is no output-file argument.

tuios layout export <name>

Redirect it yourself to save it, and replay it with tuios tape exec:

tuios layout export dev > dev.tape
tuios tape exec dev.tape

ssh

Run TUIOS as an SSH server.

tuios ssh [flags]

Flags:

• --port - SSH server port (default: 2222)
• --host - SSH server host (default: localhost)
• --key-path - Path to SSH host key (auto-generated if not specified)
• --default-session - Session name every connection lands in
• --ephemeral - Run standalone, with no daemon

Examples:

# Start on default port
tuios ssh

# Custom port
tuios ssh --port 8022

# Listen on all interfaces
tuios ssh --host 0.0.0.0 --port 2222

# Every client joins the same shared session
tuios ssh --default-session shared

# Each connection gets a throwaway instance, nothing persists
tuios ssh --ephemeral

# Connect from another machine
ssh -p 2222 user@hostname

With --default-session, connecting clients attach to one named session and see each other's work, which is the pairing setup. With --ephemeral there is no daemon at all, so nothing survives disconnection and none of the session commands (ls, attach, send-keys) can reach the connection.

config

Manage TUIOS configuration.

config path

Print configuration file path.

tuios config path

config edit

Edit configuration in $EDITOR.

tuios config edit

config reset

Reset configuration to defaults.

tuios config reset

keybinds

View keybinding configuration. Aliases: keys, kb.

keybinds list

List all keybindings.

tuios keybinds list

keybinds list-custom

List only customized keybindings.

tuios keybinds list-custom

tape

Manage and run tape automation scripts.

tape play

Run a tape file in interactive mode. This always starts a visible TUI and plays the script inside it, so you can watch the automation happen. Press Ctrl+P to pause and resume.

tuios tape play <file.tape>

This subcommand has no flags of its own; only the global flags apply. There is no headless or --visible option. To run a script without a new TUI, use tape exec against a daemon session.

tape validate

Validate tape file syntax.

tuios tape validate <file.tape>

tape list

List all saved tape recordings.

tuios tape list

tape dir

Show tape recordings directory path.

tuios tape dir

tape show

Display contents of a tape file.

tuios tape show <name>

tape delete

Delete a tape recording.

tuios tape delete <name>

tape exec

Execute a tape script against a running TUIOS session (remote execution).

tuios tape exec <file.tape> [flags]

Flags:

• -s, --session <name> - Target session (default: most recently active)

This allows you to run tape scripts without starting a new TUIOS instance. The script runs against an already-running daemon session. See Remote Tape Execution for details.

Remote Control Commands

Control a running TUIOS session from external scripts and tools. These commands require a daemon session to be running. They all take -s/--session and default to the most recently active session when it is omitted.

These are a convenience layer over the daemon's JSON control protocol. If you are writing more than a few calls, go to the protocol directly.

send-keys

Send keystrokes to a TUIOS session.

tuios send-keys <keys> [flags]

Flags:

• -s, --session <name> - Target session (default: most recently active)
• -w, --window <name|id> - Target window by name or ID (default: focused window)
• -l, --literal - Send keys directly to terminal PTY (bypass TUIOS)
• -r, --raw - Treat each character as a separate key

Key Format (default mode, not --literal):

• Single keys: i, n, Enter, Escape, Space
• Key combos: ctrl+b, alt+1, shift+Enter. Case-insensitive
• Sequences: separated by a space or a comma, "ctrl+b q" or "ctrl+b,q"
• Modifiers: ctrl, alt, shift, super, meta
• Special keys: Enter, Return, Space, Tab, Escape, Esc, Backspace, Delete, Up, Down, Left, Right, Home, End, PageUp, PageDown, F1 through F12

The PREFIX token. $PREFIX and PREFIX both expand to the configured leader key, ctrl+b by default. Use it so scripts keep working when someone rebinds their prefix:

tuios send-keys "$PREFIX q"

In bash and zsh, $PREFIX inside double quotes is expanded by the shell before TUIOS sees it. Use single quotes, or the bare PREFIX spelling, to pass it through:

tuios send-keys 'PREFIX q'

Window targeting. --window resolves its argument in this order, first match wins:

1. Custom name (a name set with RenameWindow)
2. Window title
3. Exact full UUID
4. UUID prefix, 8 or more characters

A custom name that happens to equal another window's title therefore wins. Use a full or prefixed ID when you need certainty.

Examples:

# Enter terminal mode
tuios send-keys i

# Send key combo
tuios send-keys "ctrl+b q"

# Send to specific session
tuios send-keys -s mysession Escape

# Send literal text to terminal (use --raw to prevent space splitting)
tuios send-keys --literal --raw "echo hello"

# Target a window by name, then by ID prefix
tuios send-keys --window "Server" --literal --raw "echo hello"
tuios send-keys --window a1b2c3d4 --literal "ls"

capture-pane

Capture the content of a terminal pane to stdout.

tuios capture-pane [flags]

Flags:

• -s, --session <name> - Target session
• -w, --window <name|id> - Target window by name or ID
• -S, --scrollback - Include full scrollback history (not just visible screen)
• --ansi - Preserve ANSI escape codes (colors, styles)

Examples:

# Capture focused window
tuios capture-pane

# Capture specific window with scrollback
tuios capture-pane -w mywindow --scrollback

# Pipe to file with colors
tuios capture-pane --ansi > pane.txt

run-command

Execute a TUIOS command (same commands available in tape scripts).

tuios run-command <command> [args...] [flags]

Flags:

• -s, --session <name> - Target session (default: most recently active)
• --json - Output result as JSON
• --list - List all available commands

Verb names are PascalCase and tuios run-command --list always prints the set the installed binary supports. The table below is that list.

Windows:

Modes and layout:

Workspaces:

Appearance:

Queries:

The three query verbs are what the dedicated list-windows, get-window, and session-info commands call internally. Use the dedicated commands; they are the same request with a shorter spelling.

Examples:

# List all available commands
tuios run-command --list

# Create a new window
tuios run-command NewWindow "my-terminal"

# Get JSON output with window ID
tuios run-command --json NewWindow "dev"

# Switch workspace
tuios run-command SwitchWorkspace 2

# Split and equalize
tuios run-command Split vertical
tuios run-command EqualizeSplits

# Target specific session
tuios run-command -s mysession ToggleTiling

JSON output. --json prints a result envelope with the verb's own result fields merged into the top level. There is no data wrapper:

{
  "success": true,
  "message": "command executed",
  "window_id": "79d10b84-414e-44cf-a0f3-20ac2c1fcc48",
  "name": "dev"
}

So a new window's ID is at .window_id, not .data.window_id. Branch on .success, not on .message; the message is human-readable text and its wording is not a stable interface. On failure the object is {"success": false, "error": "..."} and the exit code is 1.

set-config

Change TUIOS configuration at runtime.

tuios set-config <path> <value> [flags]

Flags:

• -s, --session <name> - Target session (default: most recently active)

Available Paths:

Examples:

tuios set-config dockbar_position top
tuios set-config border_style rounded
tuios set-config animations toggle

get-config

Read back a session option previously set with set-config.

tuios get-config <path> [flags]

Flags:

• -s, --session <name> - Target session (default: most recently active)

tuios get-config border_style

Options are stored in daemon-owned state, so this works whether or not a TUI client is attached. It reports the option's recorded value, which is not necessarily what a running client is drawing if the client was started with a conflicting flag.

list-verbs

List the JSON control-protocol verbs the daemon supports, with their parameters and an example call.

tuios list-verbs [verb] [flags]

Flags:

• --json - Output as JSON

# Every verb with its parameters
tuios list-verbs

# Just one verb
tuios list-verbs capture-pane

# Machine-readable, for a script or an agent
tuios list-verbs --json

These are the kebab-case protocol verbs, a different set from the PascalCase run-command verbs above. The output is generated from the daemon's own verb registry, so it describes the binary you are running rather than a document that can drift. See Control Protocol.

Inspection Commands

Query the state of a running TUIOS session. These commands are designed for scripting and return structured data.

list-windows

List all windows in a TUIOS session.

tuios list-windows [flags]

Flags:

• -s, --session <name> - Target session (default: most recently active)
• --json - Output as JSON

Examples:

# Table format
tuios list-windows

# JSON for scripting
tuios list-windows --json

# Query specific session
tuios list-windows -s mysession --json

JSON Output:

{
  "success": true,
  "message": "command executed",
  "windows": [
    {
      "window_id": "79d10b84-414e-44cf-a0f3-20ac2c1fcc48",
      "index": 0,
      "title": "Terminal 79d10b84",
      "display_name": "dev",
      "custom_name": "dev",
      "workspace": 1,
      "focused": true,
      "minimized": false,
      "x": 0,
      "y": 0,
      "width": 120,
      "height": 40,
      "pty_id": "5643204f-ec1d-49d9-9385-ded247ba75cb"
    }
  ],
  "total": 1,
  "focused_index": 0,
  "focused_window_id": "79d10b84-414e-44cf-a0f3-20ac2c1fcc48",
  "current_workspace": 1,
  "workspace_windows": [1, 0, 0, 0, 0, 0, 0, 0, 0]
}

Notes on the shape:

• The identifier field is window_id, a full UUID. There is no id.
• The top-level focused pointer is focused_window_id. There is no focused_id.
• custom_name is present only on windows that have been renamed. display_name is always present and is the custom name when set, the title otherwise.
• workspace_windows is a per-workspace window count, indexed from workspace 1 at position 0.
• success and message are the result envelope every remote command shares.

get-window

Get detailed information about a specific window.

tuios get-window [id-or-name] [flags]

Arguments:

• id-or-name - Window ID or custom name. If omitted, returns the focused window.

Flags:

• -s, --session <name> - Target session (default: most recently active)
• --json - Output as JSON

Examples:

# Get focused window
tuios get-window --json

# Get specific window by name
tuios get-window dev --json

# Get window by ID
tuios get-window a1b2c3d4 --json

# Query specific session
tuios get-window -s mysession --json

JSON Output: the same window object list-windows emits, flattened into the result envelope rather than nested.

{
  "success": true,
  "message": "command executed",
  "window_id": "79d10b84-414e-44cf-a0f3-20ac2c1fcc48",
  "index": 0,
  "title": "Terminal 79d10b84",
  "custom_name": "dev",
  "display_name": "dev",
  "workspace": 1,
  "focused": true,
  "minimized": false,
  "x": 0,
  "y": 0,
  "width": 120,
  "height": 40,
  "pty_id": "5643204f-ec1d-49d9-9385-ded247ba75cb"
}

session-info

Get information about the TUIOS session state.

tuios session-info [flags]

Flags:

• -s, --session <name> - Target session (default: most recently active)
• --json - Output as JSON

Examples:

tuios session-info --json

# Query specific session
tuios session-info -s mysession --json

JSON Output:

{
  "success": true,
  "message": "command executed",
  "session_name": "work",
  "session_id": "06dd756e-0507-4656-ae8a-6cabab7631cf",
  "mode": "unknown",
  "current_workspace": 1,
  "num_workspaces": 9,
  "layout_mode": "bsp",
  "window_count": 3,
  "tiling_mode": "tiling",
  "master_ratio": 0.5,
  "width": 120,
  "height": 40,
  "tui_attached": true
}

completion

Generate shell completion scripts.

tuios completion [bash|zsh|fish|powershell]

Examples:

# Bash
tuios completion bash > /etc/bash_completion.d/tuios

# Zsh
tuios completion zsh > "${fpath[1]}/_tuios"

# Fish
tuios completion fish > ~/.config/fish/completions/tuios.fish

# PowerShell
tuios completion powershell > tuios.ps1

Scripting Examples

The remote control and inspection commands are enough for shell scripting. Three field names carry most of the mistakes: window IDs are .window_id, the focused window is .focused_window_id, and the window count is .window_count.

Create a Development Layout

#!/bin/bash
set -euo pipefail

# Create windows and capture their IDs. run-command --json flattens result
# fields to the top level, so the ID is .window_id and not .data.window_id.
EDITOR_ID=$(tuios run-command --json NewWindow "editor" | jq -r '.window_id')
TERM_ID=$(tuios run-command --json NewWindow "terminal" | jq -r '.window_id')
LOGS_ID=$(tuios run-command --json NewWindow "logs" | jq -r '.window_id')

# Enable tiling. EnableTiling is idempotent; ToggleTiling is not
tuios run-command EnableTiling

# Send commands to each window in turn
tuios run-command FocusWindow "$EDITOR_ID"
tuios send-keys --literal --raw "nvim ."
tuios send-keys Enter

tuios run-command FocusWindow "$LOGS_ID"
tuios send-keys --literal --raw "tail -f /var/log/system.log"
tuios send-keys Enter

tuios run-command FocusWindow "$TERM_ID"

Prefer EnableTiling and DisableTiling over ToggleTiling in scripts. A toggle depends on the state you happened to start in, so rerunning the script produces the opposite result.

Interactive Window Selector with fzf

#!/bin/bash
WINDOW=$(tuios list-windows --json | \
    jq -r '.windows[] | "\(.display_name)\t\(.window_id)"' | \
    fzf --with-nth=1 | \
    cut -f2)

if [ -n "$WINDOW" ]; then
    tuios run-command FocusWindow "$WINDOW"
fi

Wait for Window Count

#!/bin/bash
while true; do
    WINDOW_COUNT=$(tuios session-info --json | jq '.window_count')
    if [ "$WINDOW_COUNT" -ge 3 ]; then
        echo "Ready with $WINDOW_COUNT windows"
        break
    fi
    sleep 0.5
done

A poll loop like this one is what the control protocol's wait-for verb exists to replace. If you are writing anything that has to wait on session state, do it over the control protocol instead of sleeping.

Beyond the CLI

Each CLI invocation opens its own connection to the daemon, runs one request, and exits. That is fine for a handful of calls and wasteful for a loop. It also flattens every failure into exit code 1, with the reason only in text on stderr.

For anything larger, talk to the daemon directly. It speaks a line-oriented JSON protocol on the same socket, with structured error codes, blocking waits, and a subscribable event stream. See Control Protocol, and run tuios list-verbs to get the schema from the binary itself.

Environment Variables

TUIOS_DEBUG_INTERNAL

Enable internal debug logging (same as --debug flag).

export TUIOS_DEBUG_INTERNAL=1
tuios

EDITOR / VISUAL

Set editor for tuios config edit.

export EDITOR=vim
tuios config edit

XDG_CONFIG_HOME

Override config directory location.

export XDG_CONFIG_HOME=~/.custom_config
tuios config path

COLORTERM

Enable true color support (usually set automatically).

export COLORTERM=truecolor

Graphics Environment Variables

Control graphics protocol support (experimental features):

# Kitty graphics protocol
export TUIOS_KITTY_GRAPHICS=1  # Force enable
export TUIOS_KITTY_GRAPHICS=0  # Force disable

# Sixel graphics protocol
export TUIOS_SIXEL_GRAPHICS=1  # Force enable
export TUIOS_SIXEL_GRAPHICS=0  # Force disable

# Debug logging for graphics
export TUIOS_DEBUG_CAPS=1      # Log capability detection to /tmp/tuios_caps.log

Exit Codes

• 0 - Success
• 1 - Error: command failed, invalid arguments, no daemon, session or window not found

There is only one failure code. The CLI does not distinguish "no such session" from "daemon not running" from "bad argument" by exit status, and with --json the reason is in the error field rather than the status. If your script needs to tell those cases apart, use the control protocol, which returns structured error codes.

Examples

Run with custom theme and border

tuios --theme dracula --border-style thick

Daemon mode workflow

# Create a new session
tuios new work

# ... do some work, then detach with Ctrl+B d ...

# List sessions
tuios ls

# Reattach later
tuios attach work

# Kill when done
tuios kill-session work

Start SSH server for remote access

tuios ssh --host 0.0.0.0 --port 2222

Run tape automation

# In a fresh TUI you can watch
tuios tape play examples/demo.tape

# Against a session that is already running
tuios tape exec examples/demo.tape

Edit configuration

tuios config edit

List custom keybindings

tuios keybinds list-custom

Related Documentation