# Getting Started

URL: https://tuios.dev/docs/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](https://tuios.dev/learn) 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](https://www.nerdfonts.com/) makes the icons render; without one, start TUIOS with `--ascii-only`.

## Install

> > macOS and Linux:
> >
> > ```bash
> > brew install tuios
> > ```
>
> > ```bash
> > yay -S tuios-bin
> > ```
>
> > Linux and macOS. Installs the `tuios` binary into `/usr/local/bin`, `~/.local/bin` or `~/bin`, whichever it can write to.
> >
> > ```bash
> > curl -fsSL https://raw.githubusercontent.com/Gaurav-Gosain/tuios/main/install.sh | bash
> > ```
>
> > ```bash
> > nix run github:Gaurav-Gosain/tuios#tuios
> > ```
> >
> > The 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.
> >
> > ```bash
> > go install github.com/Gaurav-Gosain/tuios/cmd/tuios@latest
> > ```
>
> > ```bash
> > docker run -it --rm ghcr.io/gaurav-gosain/tuios:latest
> > ```

Pre-built binaries for Linux, macOS, Windows and FreeBSD are on the [releases page](https://github.com/Gaurav-Gosain/tuios/releases).

Check the install:

```bash
tuios --version
```

The 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](https://tuios.dev/docs/web) to install it.

### Build from source

```bash
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
> >
> > ```bash
> > tuios
> > ```
> >
> > The first run creates a session called `session-0` and shows a welcome screen with four keys on it:
> >
> > *[An interactive figure goes here. Open the page to use it.](https://tuios.dev/docs/getting-started)*
> >
> > 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:
> >
> > ```bash
> > ls
> > ```
>
> > ### Go 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](https://tuios.dev/docs/configuration).

## Keys for day one

On macOS, read Alt as Opt. If an Opt chord types a strange character instead, see the [macOS notes](https://tuios.dev/docs/keybindings#macos).

**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](https://tuios.dev/docs/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](https://tuios.dev/docs/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:

```bash
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 it
```

Inside 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](https://tuios.dev/docs/sessions) explains both kinds and exactly what survives a restart.

## Make it yours

```bash
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 theme
```

Most settings can also be changed live on the settings page, Ctrl+B ,. See [Configuration](https://tuios.dev/docs/configuration) for every option.

## Shell completions

```bash
# 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

*[An interactive figure goes here. Open the page to use it.](https://tuios.dev/docs/getting-started)*