Getting Started with TUIOS

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

Installation

Package Managers

brew install tuios

# Using yay
yay -S tuios-bin

# Using paru  
paru -S tuios-bin

# Run directly
nix run github:Gaurav-Gosain/tuios#tuios

# Or add to your configuration
nix-shell -p tuios

Quick Install Script

Linux/macOS:

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

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

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:

• hjkl - Move focus (vim-style)
• Tab - Next window
• ShiftTab - Previous window

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 - Minimize focused window

Workspaces

TUIOS provides 9 workspaces (like virtual desktops):

• CtrlB 1-9 - Switch to workspace 1-9
• CtrlB Shift1-9 - Move window to workspace and follow

Tiling

• t - Toggle automatic tiling mode
• CtrlB f - Fullscreen focused window
• CtrlB h - Snap window left (50% width)
• CtrlB l - Snap window right (50% width)

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