Getting Started with TUIOS

This guide will help you install TUIOS and learn the essential operations.

Installation

Package Managers

brew tap Gaurav-Gosain/tap
brew install tuios

# Using yay
yay -S tuios-bin

# Using paru  
paru -S tuios-bin

nix run github:Gaurav-Gosain/tuios#tuios

Quick Install Script

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/Gaurav-Gosain/tuios/main/install.sh | bash

This installs the tuios binary only. The browser terminal is a second binary, tuios-web, which you install separately. See Web Terminal.

Alternative Methods

go install github.com/Gaurav-Gosain/tuios/cmd/tuios@latest

docker run -it --rm ghcr.io/gaurav-gosain/tuios:latest

git clone https://github.com/gaurav-gosain/tuios.git
cd tuios
go build -o tuios ./cmd/tuios
./tuios

First Launch

Simply run:

tuios

Understanding Modes

TUIOS has two primary modes:

1. Window Management Mode

The mode you start in. This is where you:

• Navigate between windows
• Create/close/rename windows
• Switch workspaces
• Tile windows
• Use mouse to drag/resize

Visual Indicator: Windows have colored borders and you see the dockbar at bottom.

2. Terminal Mode

Where you interact with the terminal inside a window. Your keypresses go directly to the shell/application.

Visual Indicator: The active window is fully focused, keyboard input is captured.

Essential Keybindings

Command Palette

The fastest way to discover what TUIOS can do is the Command Palette:

• Press Ctrl+P from any mode to open it
• Type to fuzzy-search commands, keybindings, and actions
• Press Enter to execute

Creating Your First Window

From Window Management Mode:

• Press n to create a new window

Or from any mode:

• Press CtrlB, then c

Window Navigation

In Window Management Mode:

• Tab - Next window
• ShiftTab - Previous window
• Arrow keys - Move focus directionally
• 1-9 - Select window by number

In Terminal Mode (without leaving the mode):

• AltN / AltP - Next/Previous window (Linux/Windows)
• OptTab / OptShiftTab - Next/Previous window (macOS)

Or click with your mouse!

Window Management

From any mode (using CtrlB prefix):

• CtrlB c - Create new window
• CtrlB x - Close focused window
• CtrlB r - Rename focused window
• CtrlB m m - Minimize focused window (CtrlB m opens the minimize menu)
• CtrlB , - Open the settings page

Workspaces

TUIOS provides 9 workspaces (like virtual desktops):

• Alt1-9 - Switch to workspace 1-9
• AltShift1-9 - Move window to workspace and follow
• CtrlB w then 1-9 - The same, through the workspace prefix menu

Tiling

• t - Toggle automatic tiling mode
• CtrlB z - Zoom the focused pane to fullscreen
• f - Fullscreen the focused window (window mode)
• h / l - Snap window left / right at 50% width (window mode)

Layout Templates

Save and restore window arrangements for repeatable workflows:

• CtrlB L - Load a saved layout template
• Use tuios layout list to see saved layouts
• Use tuios layout dir to find the templates directory
• Use tuios layout export <name> to export a layout

Layout templates remember the number of windows, their positions, sizes, and workspace assignments so you can recreate a complex setup with a single command.

Copy Mode (Scrollback)

Access 10,000 lines of scrollback with vim-style navigation:

• CtrlB [ - Enter copy mode
• hjkl - Move cursor
• / - Search forward
• v - Start visual selection
• y - Copy selection to clipboard
• Esc - Exit copy mode

Help & Quit

• CtrlB ? - Toggle help overlay
• CtrlB q - Quit TUIOS

Example Workflow

Let's create a development setup:

tuios

ls
vim myfile.go

Command Line Options

TUIOS supports many flags:

# Run with a specific theme
tuios --theme dracula

# List all available themes (300+)
tuios --list-themes

# Preview a theme's colors
tuios --preview-theme nord

# Enable debug mode
tuios --debug

# Use ASCII-only (no Nerd Font icons)
tuios --ascii-only

# Show pressed keys overlay (for demos)
tuios --show-keys

# Custom border style
tuios --border-style thick

# Custom dockbar position
tuios --dockbar-position top

Daemon Mode (Session Persistence)

Create persistent sessions that survive disconnection (like tmux):

# Create a new session
tuios new mysession

# ... work in TUIOS ...
# Detach with Ctrl+B d

# List sessions
tuios ls

# Reattach later
tuios attach mysession

SSH Server Mode

Run TUIOS as an SSH server for remote access:

# Start on default port (2222)
tuios ssh

# Custom port
tuios ssh --port 8022

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

Connect from another machine:

ssh -p 2222 user@hostname

Each SSH connection gets its own isolated TUIOS session!

Configuration

TUIOS stores its configuration in a TOML file:

# Edit configuration
tuios config edit

# Print config file path
tuios config path

# Reset to defaults
tuios config reset

# List all keybindings
tuios keybinds list

# List only custom keybindings
tuios keybinds list-custom

See the Configuration guide for details.

Shell Completions

Generate shell completions for your shell:

# 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

Next Steps