Remote Control

Overview

TUIOS remote control lets you manipulate running sessions without attaching to them. Send keystrokes, execute commands, change settings, and query session state—all from the CLI.

Remote control requires the daemon to be running and a session to be active. The TUI client processes commands via the daemon.

Send Keys

Send keystrokes to a running session.

Basic Usage

tuios send-keys <keys>

By default, keys are sent to TUIOS itself (for window management, mode switching, etc.).

Key Format

Single keys:

tuios send-keys i          # Press 'i' (enter terminal mode)
tuios send-keys Enter      # Press Enter
tuios send-keys Escape     # Press Escape
tuios send-keys Space      # Press Space

Key combinations:

tuios send-keys ctrl+b     # Prefix key
tuios send-keys alt+1      # Switch to workspace 1  
tuios send-keys shift+Enter

Sequences (space or comma separated):

tuios send-keys "ctrl+b n"     # Prefix + new window
tuios send-keys "ctrl+b,q"     # Prefix + quit
tuios send-keys "i Enter"      # Terminal mode + Enter

Special Tokens

$PREFIX or PREFIX - Expands to configured leader key (default ctrl+b):

tuios send-keys "$PREFIX n"    # Prefix + new window
tuios send-keys "PREFIX q"     # Prefix + quit

Supported Keys

Modifiers:

ctrl, alt, shift, super, meta

Special keys:

Enter, Return, Space, Tab
Escape, Esc, Backspace, Delete
Up, Down, Left, Right
Home, End, PageUp, PageDown, Insert
F1 through F12

Case insensitive:

tuios send-keys ctrl+B  # Same as ctrl+b
tuios send-keys ENTER   # Same as Enter

Flags

`--literal` - Send to Terminal PTY

Send keys directly to the focused terminal (bypass TUIOS):

tuios send-keys --literal "ls -la"
tuios send-keys --literal Enter

With --literal, spaces split keys into separate characters unless you use --raw.

`--raw` - Treat Each Character as a Key

Prevent splitting on spaces/commas:

tuios send-keys --raw "hello world"         # Each char sent separately
tuios send-keys --literal --raw "echo hi"   # Literal text with spaces

`--session <name>` - Target Specific Session

Default: most recently active session.

tuios send-keys --session dev Escape
tuios send-keys -s prod "ctrl+b n"

Examples

Enter terminal mode and run command:

tuios send-keys i
tuios send-keys --literal --raw "git status"
tuios send-keys --literal Enter

Create new window:

tuios send-keys "ctrl+b n"

Switch workspace and create window:

tuios send-keys alt+2
tuios send-keys "$PREFIX n"

Send Ctrl+C to interrupt:

tuios send-keys ctrl+c

Quit TUIOS:

tuios send-keys "ctrl+b q"

Run Command

Execute tape commands in a running session.

Basic Usage

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

Commands are from the tape scripting language.

List Available Commands

tuios run-command --list

Available commands for 'tuios run-command':

  NewWindow [name]                    Create a new terminal window
  CloseWindow [name]                  Close window(s)
  NextWindow                          Focus the next window
  FocusWindow <name>                  Focus a window by name
  ToggleTiling                        Toggle tiling mode
  SwitchWorkspace 1-9                 Switch to workspace N
  SetTheme themename                  Change the color theme
  ...

Window Management

Create windows:

tuios run-command NewWindow "Server"
tuios run-command NewWindow          # Auto-named

Focus windows:

tuios run-command NextWindow
tuios run-command PrevWindow
tuios run-command FocusWindow "Server"

Close windows:

tuios run-command CloseWindow           # Close focused
tuios run-command CloseWindow "Build"   # Close all named "Build"

Rename windows:

tuios run-command RenameWindow "New Name"              # Rename focused
tuios run-command RenameWindow "Old Name" "New Name"   # Rename by name

Minimize/restore:

tuios run-command MinimizeWindow
tuios run-command MinimizeWindow "Server"
tuios run-command RestoreWindow

Mode Switching

tuios run-command TerminalMode           # Enter terminal mode
tuios run-command WindowManagementMode   # Enter window mode

Tiling

Toggle tiling:

tuios run-command ToggleTiling
tuios run-command EnableTiling
tuios run-command DisableTiling

Snap windows:

tuios run-command SnapLeft
tuios run-command SnapRight  
tuios run-command SnapFullscreen

BSP tiling:

tuios run-command Split horizontal
tuios run-command Split vertical
tuios run-command RotateSplit
tuios run-command EqualizeSplits

Workspaces

Switch workspace:

tuios run-command SwitchWorkspace 2

Move window to workspace:

tuios run-command MoveToWorkspace 3

Configuration

Change settings:

tuios run-command SetDockbarPosition top
tuios run-command SetBorderStyle rounded
tuios run-command SetTheme dracula

Animations:

tuios run-command EnableAnimations
tuios run-command DisableAnimations
tuios run-command ToggleAnimations

Show notifications:

tuios run-command ShowNotification "Build complete!" success
tuios run-command ShowNotification "Error occurred" error

JSON Output for Scripting

Get machine-readable output:

tuios run-command --json NewWindow "Server"

{
  "success": true,
  "message": "command executed",
  "window_id": "abc123-def456"
}

Use with jq:

# Get window ID from new window
WINDOW_ID=$(tuios run-command --json NewWindow | jq -r '.window_id')
echo "Created window: $WINDOW_ID"

Session Targeting

tuios run-command --session dev NewWindow
tuios run-command -s prod ToggleTiling

Set Config

Change configuration at runtime.

Basic Usage

tuios set-config <path> <value>

Supported Paths

Dockbar position:

tuios set-config dockbar_position top
tuios set-config dockbar_position bottom

Border style:

tuios set-config border_style rounded
tuios set-config border_style thick
tuios set-config border_style hidden

Animations:

tuios set-config animations true
tuios set-config animations false
tuios set-config animations toggle

Window buttons:

tuios set-config hide_window_buttons true
tuios set-config hide_window_buttons false

Session Targeting

tuios set-config --session dev animations false

Config changes apply to the running session only. They don’t persist to the config file. Edit ~/.config/tuios/config.toml for permanent changes.

Query State

Inspect session and window state from the CLI.

List Windows

tuios list-windows

╭─────────────┬──────────┬───────────┬───────────╮
│ ID          │ Name     │ Workspace │ Focused   │
├─────────────┼──────────┼───────────┼───────────┤
│ abc123      │ Server   │ 1         │ yes       │
│ def456      │ Editor   │ 1         │ no        │
│ ghi789      │ Build    │ 2         │ no        │
╰─────────────┴──────────┴───────────┴───────────╯

JSON output:

tuios list-windows --json

{
  "success": true,
  "windows": [
    {
      "window_id": "abc123-def456",
      "index": 0,
      "title": "zsh",
      "display_name": "Server",
      "workspace": 1,
      "focused": true,
      "minimized": false,
      "x": 0,
      "y": 0,
      "width": 120,
      "height": 40
    }
  ],
  "total": 3,
  "focused_window_id": "abc123-def456",
  "current_workspace": 1
}

Use with jq:

# Get focused window ID
tuios list-windows --json | jq -r '.focused_window_id'

# List window names
tuios list-windows --json | jq -r '.windows[].display_name'

# Count windows per workspace
tuios list-windows --json | jq '.workspace_windows'

Get Window Info

Focused window:

tuios get-window
tuios get-window --json

By name:

tuios get-window "Server"
tuios get-window "Server" --json

By ID:

tuios get-window abc123-def456

Session Info

tuios session-info

╭────────────────────┬───────────────╮
│ Session Name       │ dev           │
│ Current Workspace  │ 2             │
│ Window Count       │ 5             │
│ Tiling Mode        │ enabled       │
│ Mode               │ terminal      │
╰────────────────────┴───────────────╯

JSON output:

tuios session-info --json

{
  "success": true,
  "session_name": "dev",
  "current_workspace": 2,
  "num_workspaces": 9,
  "window_count": 5,
  "tiling_mode": "tiling",
  "mode": "terminal",
  "width": 200,
  "height": 50
}

Use with jq:

# Check if tiling is enabled
if [ "$(tuios session-info --json | jq -r '.tiling_mode')" = "tiling" ]; then
  echo "Tiling is enabled"
fi

# Get current workspace
WS=$(tuios session-info --json | jq -r '.current_workspace')
echo "Current workspace: $WS"

Execute Tape Scripts

Run entire tape scripts remotely.

Basic Usage

tuios tape exec <file.tape>

Executes the tape script in the running session without attaching.

Example Script

setup.tape:

NewWindow "Server"
SwitchWorkspace 1

NewWindow "Editor"  
SwitchWorkspace 1

NewWindow "Build"
SwitchWorkspace 2

FocusWindow "Server"
ShowNotification "Workspace setup complete" success

Execute:

tuios tape exec setup.tape

Session Targeting

tuios tape exec --session dev setup.tape

For complex automation, use tape scripts instead of chaining run-command calls. Scripts are atomic and easier to maintain.

Automation Examples

Development Environment Setup

#!/bin/bash
# setup-dev.sh - Create development workspace

SESSION="dev"

# Create session if not exists
if ! tuios ls | grep -q "$SESSION"; then
  tuios new "$SESSION" &
  sleep 2
fi

# Set up windows
tuios run-command -s "$SESSION" NewWindow "Server"
tuios send-keys -s "$SESSION" --literal --raw "npm run dev"
tuios send-keys -s "$SESSION" --literal Enter

tuios run-command -s "$SESSION" NewWindow "Editor"
tuios send-keys -s "$SESSION" --literal --raw "nvim src/"
tuios send-keys -s "$SESSION" --literal Enter

tuios run-command -s "$SESSION" NewWindow "Git"
tuios send-keys -s "$SESSION" --literal --raw "git status"
tuios send-keys -s "$SESSION" --literal Enter

tuios run-command -s "$SESSION" SwitchWorkspace 1
tuios run-command -s "$SESSION" FocusWindow "Server"

echo "Development environment ready. Attach with: tuios attach $SESSION"

Check Build Status

#!/bin/bash
# check-build.sh - Query window to see if build finished

WINDOW_NAME="Build"

# Get window info
INFO=$(tuios get-window "$WINDOW_NAME" --json)

if echo "$INFO" | jq -e '.success' > /dev/null; then
  echo "Build window found"
  # Could parse terminal output here if needed
else
  echo "Build window not found"
  exit 1
fi

Dynamic Workspace Configuration

#!/bin/bash
# toggle-tiling.sh - Toggle tiling based on window count

INFO=$(tuios session-info --json)
WINDOW_COUNT=$(echo "$INFO" | jq -r '.window_count')

if [ "$WINDOW_COUNT" -gt 3 ]; then
  echo "Many windows, enabling tiling"
  tuios run-command EnableTiling
else
  echo "Few windows, disabling tiling"
  tuios run-command DisableTiling
fi

Send Notifications on Events

#!/bin/bash
# notify-build.sh - Show notification when build completes

make build && \
  tuios run-command ShowNotification "Build succeeded!" success || \
  tuios run-command ShowNotification "Build failed!" error

Shell Completion

TUIOS provides tab completion for all remote control commands. Generate completions:

# 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

Features:

Session name completion
Command name completion
Argument completion (e.g., workspace numbers, border styles)
Key name completion for send-keys

Use Tab after tuios send-keys to see all available key names.

Troubleshooting

Command Not Executing

Check daemon is running:

tuios ls

Check session exists:

tuios ls
# Verify target session is listed

Check TUI client is attached: Remote commands require a TUI client to be attached to the session.

tuios ls
# "Attached" column should show "yes"

If no client is attached, attach one:

tuios attach mysession

Timeouts

Commands timeout after 5 seconds if no response. Possible causes:

TUI client frozen/crashed
Daemon overloaded
Network issue (if using SSH)

Solution:

tuios kill-session mysession
tuios new mysession

Wrong Session Targeted

By default, commands target the most recently active session. Always specify session:

tuios run-command --session mysession NewWindow

Daemon Mode

Session lifecycle and daemon management

Tape Scripting

Automation language reference

Library Usage

Embedding TUIOS in Go apps

Keybindings

All available key commands

​Overview

​Send Keys

​Basic Usage

​Key Format

​Special Tokens

​Supported Keys

​Flags

​--literal - Send to Terminal PTY

​--raw - Treat Each Character as a Key

​--session <name> - Target Specific Session

​Examples

​Run Command

​Basic Usage

​List Available Commands

​Window Management

​Mode Switching

​Tiling

​Workspaces

​Configuration

​JSON Output for Scripting

​Session Targeting

​Set Config

​Basic Usage

​Supported Paths

​Session Targeting

​Query State

​List Windows

​Get Window Info

​Session Info

​Execute Tape Scripts

​Basic Usage

​Example Script

​Session Targeting

​Automation Examples

​Development Environment Setup

​Check Build Status

​Dynamic Workspace Configuration

​Send Notifications on Events

​Shell Completion

​Troubleshooting

​Command Not Executing

​Timeouts

​Wrong Session Targeted

​See Also

Daemon Mode

Tape Scripting

Library Usage

Keybindings

Overview

Send Keys

Basic Usage

Key Format

Special Tokens

Supported Keys

Flags

`--literal` - Send to Terminal PTY

`--raw` - Treat Each Character as a Key

`--session <name>` - Target Specific Session

Examples

Run Command

Basic Usage

List Available Commands

Window Management

Mode Switching

Tiling

Workspaces

Configuration

JSON Output for Scripting

Session Targeting

Set Config

Basic Usage

Supported Paths

Session Targeting

Query State

List Windows

Get Window Info

Session Info

Execute Tape Scripts

Basic Usage

Example Script

Session Targeting

Automation Examples

Development Environment Setup

Check Build Status

Dynamic Workspace Configuration

Send Notifications on Events

Shell Completion

Troubleshooting

Command Not Executing

Timeouts

Wrong Session Targeted

See Also