Getting Started
Install TUIOS, open your first windows, and learn the keys you need on day one.
This page takes you from nothing to a working session in about five minutes.
Want to try it first?
Learn tuios runs the real app in your browser, with a pretend shell. Press the keys yourself, five minutes, nothing to install.
You need a terminal with true color support. A Nerd Font makes the icons render; without one, start TUIOS with --ascii-only.
Install
macOS and Linux:
brew install tuiosyay -S tuios-binLinux and macOS. Installs the tuios binary into /usr/local/bin, ~/.local/bin or ~/bin, whichever it can write to.
curl -fsSL https://raw.githubusercontent.com/Gaurav-Gosain/tuios/main/install.sh | bashnix run github:Gaurav-Gosain/tuios#tuiosThe flake builds for x86_64-linux, aarch64-linux and aarch64-darwin. On an Intel Mac, use a release binary.
Needs Go 1.26 or newer.
go install github.com/Gaurav-Gosain/tuios/cmd/tuios@latestdocker run -it --rm ghcr.io/gaurav-gosain/tuios:latestPre-built binaries for Linux, macOS, Windows and FreeBSD are on the releases page.
Check the install:
tuios --versionThe first line names the version and the terminal emulator backend the binary was built with, for example tuios version 0.7.0 [pure-Go backend].
Keeping it up to date
If you installed with the script or a release binary, tuios update installs the newest release over the binary (tuios update --check only reports). For Homebrew, AUR, Nix and Go installs, use that tool to update. tuios update detects them and prints the right command instead.
The browser terminal is a separate binary, tuios-web. See Web Terminal to install it.
Build from source
git clone https://github.com/Gaurav-Gosain/tuios.git
cd tuios
go build -o tuios ./cmd/tuios./scripts/install.sh builds and installs into ~/.local/bin. It defaults to the libghostty-vt emulator backend, which needs zig. Run ./scripts/install.sh pure for the pure Go emulator, which needs nothing beyond Go.
Your first session
Start TUIOS
tuiosThe first run creates a session called session-0 and shows a welcome screen with four keys on it:
TUIOSTerminal UI Operating Systemn new window N new session ? help , settings
You are in window management mode. Keys here arrange windows. Nothing is sent to a shell yet.
Open a window
Press n. A window opens with your shell in it.
Type in it
Press i (or Enter) to enter terminal mode. Your keys now go to the shell. Run a command:
lsGo back to window management
Press Alt+Esc (Opt+Esc on macOS), or Ctrl+B then Esc.
A bare Esc stays in terminal mode and goes to the program, so vim and other full-screen programs keep working.
Open two more windows
Press n twice. Tiling is on by default, so each new window takes half of the focused one and all three stay visible.
Move between them with Tab and Shift+Tab, the number keys 1 to 9, or Alt+arrow keys to move to the neighbour in that direction. You can also click a window.
Try another workspace
Press Alt+2 (Opt+2 on macOS) to switch to workspace 2. It is empty. Open a window there, then press Alt+1 to go back.
Detach, and come back
Press Ctrl+B then d. TUIOS exits, but the session and its shells keep running in the background daemon. Run tuios again and everything is where you left it.
When you forget a key
Press Ctrl+P in either mode to open the command palette and search every command by name. Press Ctrl+B and wait half a second: a panel lists every key the prefix accepts next. Ctrl+B then ? opens the full help.
The two modes
| Mode | What your keys do | How to get there |
|---|---|---|
| Window management | Create, close, move, tile and switch windows | Alt+Esc, or Ctrl+B Esc |
| Terminal | Go to the program in the focused window | i or Enter |
Ctrl+B is the prefix key. It works in both modes: press it, release it, then press the next key. You can change it with keybindings.leader_key in the configuration.
Keys for day one
On macOS, read Alt as Opt. If an Opt chord types a strange character instead, see the macOS notes.
Windows
| Key | Action |
|---|---|
| n | New window (window mode) |
| w or x | Close the focused window (window mode) |
| r | Rename the focused window (window mode) |
| Tab / Shift+Tab | Next / previous window (window mode) |
| Alt+N / Alt+P | Next / previous window (both modes) |
| Alt+arrow | Focus the window in that direction (both modes) |
| 1 to 9 | Focus window by number (window mode) |
| z | Zoom the focused window to fill the screen, and back (window mode) |
| m | Minimize to the dock (window mode). M restores all. |
The prefix versions work in both modes: Ctrl+B then c (new), x (close), r (rename), n/p (next/previous), an arrow key (focus that way), 0 to 9 (focus by number), z (zoom).
Tiling
| Key | Action |
|---|---|
| t or Ctrl+B Space | Turn tiling on or off |
| - / | | Split the focused window: new window below / to the right (window mode) |
| H J K L | Swap with the neighbour left / down / up / right (window mode) |
| = | Make all splits equal (window mode) |
BSP Tiling covers preselection, resizing and the other layouts.
Workspaces
| Key | Action |
|---|---|
| Alt+1 to 9 | Switch to workspace 1 to 9 |
| Alt+Shift+1 to 9 | Move the focused window there, and follow it |
| Ctrl+B w, then a digit | Switch workspace from the prefix menu |
Ctrl+B followed directly by a digit focuses a window, not a workspace.
Scrollback and copying
| Key | Action |
|---|---|
| Mouse wheel | Scroll the window's history. Typing, or scrolling back to the bottom, returns to live output. |
| Ctrl+B [ | Enter copy mode: move with vim keys, / to search, v to select, y to copy, Esc to leave |
| Drag with the mouse | Select text. It is copied when you release. |
Everything else
| Key | Action |
|---|---|
| Ctrl+P | Command palette |
| Alt+Space or Ctrl+B a | App launcher: start any program on your $PATH in a new window |
| Ctrl+B S | Session switcher |
| Ctrl+B , | Settings page (, in window mode) |
| Ctrl+B ? | Help (? in window mode) |
| Ctrl+B d | Detach, leaving the session running |
| Ctrl+B q | Quit menu: detach, switch session, or kill this session |
The full list is on the Keybindings page, and tuios keybinds list prints the bindings in effect on your machine.
Sessions
tuios on its own attaches to your most recent session, and creates one if there is none. To manage several:
tuios new work # create a session called "work" and attach to it
tuios ls # list sessions
tuios attach work # attach to "work"
tuios kill-session work # end "work" and every window in itInside TUIOS, Ctrl+B S switches between sessions and N (window mode) creates one.
If you want a session that lives and dies with this terminal and starts no daemon, run tuios --standalone. Sessions explains both kinds and exactly what survives a restart.
Make it yours
tuios config edit # open the config file in $EDITOR
tuios config path # print where it is
tuios --list-themes # list the built-in themes
tuios --theme dracula # start with a themeMost settings can also be changed live on the settings page, Ctrl+B ,. See Configuration for every option.
Shell 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
# PowerShell
tuios completion powershell > tuios.ps1