# The Omarchy Terminal Workflow > Learn the terminal setup Omarchy ships - Foot, the shell tools, tmux, Neovim, the TUIs, and the dev tools - so you can work from the keyboard with sessions that survive closing the window. --- # The Omarchy Terminal Workflow Checked against Omarchy 4.0.4. Omarchy is built around the terminal, and it shows. A fresh install has a fast terminal with no tabs, a session manager with a key you have never pressed, an editor that starts in a mode where typing does nothing, and a pile of command names (`ff`, `tdl`, `rg`, `lsa`) you did not choose. Nobody hands you a map. This guide is the map. You learn what each piece is for, the handful of keys that matter, and how they fit together into a workflow where closing a window never loses your work. ## Prerequisite Comfort with the basics of a shell. If a command prompt still feels foreign, start with [The Terminal and Shell](/guides/the-terminal-and-shell), then [Linux From Zero](/guides/linux-from-zero). For the editor, [Editing in the Terminal](/guides/editing-in-the-terminal) teaches vim modes properly, and this guide leans on it instead of repeating it. The hotkeys and menu are in [Omarchy Menus, Panels, and the CLI](/guides/omarchy-menus-panels-and-cli). ## How to read this - **In a hurry?** Jump to [Phase 2](02-tmux-sessions-windows-and-panes.md) for tmux, the single biggest upgrade, or [Phase 4](04-tuis-and-development-tools.md) for Docker and language setup. - **Want it to make sense?** Read in order. Each phase uses the one before it. ## The phases 1. **[Your Terminal and Shell Toolkit](01-your-terminal-and-shell-toolkit.md)** - Foot, copy and paste, and the shell tools and functions Omarchy ships. 2. **[Tmux: Sessions, Windows, and Panes](02-tmux-sessions-windows-and-panes.md)** - persistent sessions, the keys that matter, and the dev layouts. 3. **[Neovim the Omarchy Way](03-neovim-the-omarchy-way.md)** - the LazyVim setup, the keys worth learning first, and the alternatives. 4. **[TUIs and Development Tools](04-tuis-and-development-tools.md)** - lazygit, lazydocker, btop, mise, Docker, databases, and AI agents. To change how any of this looks, see [Making Omarchy Comfortable](/guides/making-omarchy-comfortable). To install more software, see [Installing and Updating Software on Omarchy](/guides/installing-and-updating-software-on-omarchy). --- # Your Terminal and Shell Toolkit You press `Super + Return` and a window opens with no tabs, no menu bar, and a minimal prompt. Then you try `Ctrl + V` to paste and get a strange character, or type `ls` and see icons. None of it is broken; it is a deliberate toolkit. This phase explains the terminal, the clipboard keys that work everywhere, and the shell commands Omarchy adds. ## Foot, and why it has no tabs [Foot](https://codeberg.org/dnkl/foot) is the default terminal. The manual calls it fast, lightweight, and compatible with even old computers. It does not support native tabs or splits. Omarchy's answer is tmux (see [Phase 2](02-tmux-sessions-windows-and-panes.md)), which gives you tabs, splits, and sessions that survive in any terminal. If you would rather use another terminal, Omarchy fully supports Alacritty, Ghostty, and Kitty too. Ghostty has its own split and tab keys, listed in the manual's hotkeys chapter. - Install one from the Omarchy menu under _Install > Terminal_. - Switch the default under _Setup > Defaults > Terminal_, or run `omarchy default terminal ghostty`. - `Super + Return` always opens whichever terminal is your default. The new window starts in the current directory of the terminal you were in. Foot's settings are in `~/.config/foot/foot.ini`. The shipped file sets the font to JetBrainsMono Nerd Font at size 9, keeps 10,000 lines of scrollback, uses a block cursor that does not blink, and takes its colors from the current theme. Foot cannot reload its config, so open a new terminal to see changes. ## Copy and paste without the Ctrl + C trap In a terminal, `Ctrl + C` does not copy. It sends an interrupt to the running program, which is how you stop a command (see [The Terminal and Shell](/guides/the-terminal-and-shell)). That is why Linux terminals use `Ctrl + Shift + C` and `Ctrl + Shift + V` for copy and paste, and ordinary apps use `Ctrl + C` and `Ctrl + V`. Two rules for two kinds of window is what trips up newcomers. Omarchy removes the split. These work in every app, terminals included: | Key | What it does | |---|---| | `Super + C` | Copy | | `Super + V` | Paste | | `Super + X` | Cut (not in a terminal) | | `Super + Ctrl + V` | Open the clipboard manager | Under the hood, `Super + C` in a terminal sends the Ctrl + Insert shortcut and `Super + V` sends Shift + Insert, which terminals accept, while in other apps it sends `Ctrl + C` and `Ctrl + V`. You never have to think about which window you are in. Foot's own `Ctrl + Shift + C` and `Ctrl + Shift + V` still work, as does selecting text and pasting from the clipboard. ## The shell tools Your shell is Bash with a [Starship](https://starship.rs/) prompt. Omarchy adds modern replacements for old commands, and the manual lists the key ones: | Command | Think of it as | What it does | |---|---|---| | `ls`, `lsa`, `lt`, `lta` | `ls` | `eza` listings with color and icons. `lsa` includes hidden files, `lt` shows two levels as a tree, `lta` is the tree with hidden files. | | `ff` | `find` plus a viewer | Fuzzy-find any file under the current directory, with a preview on the right. | | `Ctrl + R` | history search | Fuzzy-search your command history with fzf. | | `cd` | `cd` | Aliased to zoxide: remembers directories you have visited so `cd oma` can jump to `~/.config/omarchy`. | | `rg pattern path` | `grep -r` | ripgrep: search file contents, for example `rg Controller app/`. | | `fd` | `find` | `fd person.rb` finds a file in the current tree. Add `/` to search the whole system, and `-H` to include hidden directories. | | `bat file` | `cat` | Syntax highlighting, line numbers, paging. | | `tldr tar` | `man` | The handful of examples you actually wanted. | | `try` | n/a | Date-stamped experiment folders in `~/Work/tries`. | Three things to know about how they behave: - **zoxide only knows places you have been.** Run `cd ~/.config/omarchy` once, and later `cd omarchy` works. Before that, `cd omarchy` fails with `Error: Directory not found`, which is also what you get when no remembered directory matches. - **`cd` still works normally** with real paths. It tries the real directory first and falls back to zoxide's memory only when the name is not a directory. - **`ff` and Neovim share a finder.** The manual notes that fzf is also behind `Space Space` in Neovim and ripgrep behind `Space S G`, so the habits transfer ([Phase 3](03-neovim-the-omarchy-way.md)). A few short aliases come with the setup: `..`, `...`, and `....` go up directories, `n` opens Neovim, `g` is `git`, `gcm` is `git commit -m`, `gcam` is `git commit -a -m`, and `gcad` is `git commit -a --amend`. That last one rewrites your most recent commit, so read it before you type it. If you are new to Git, [Git From Zero](/guides/git-from-zero) explains why amending is risky once a commit is shared. ## The helper functions Omarchy ships functions that wrap awkward command lines: | Function | What it does | |---|---| | `compress [file/dir]`, `decompress [file.tar.gz]` | Make or expand a `tar.gz` archive. | | `iso2sd [image.iso]` | Create a bootable SD card from an ISO file, picking the drive interactively. | | `format-drive [device] [name]` | Format a whole disk with one exFAT partition, which works on Windows and macOS too. | | `ga [branch]`, `gd` | Make a Git worktree and branch next to the repo and jump into it, then remove it later after a confirmation. | | `rsw [source] [destination]`, `lsw`, `dsw` | Start a background watcher that rsyncs on every change, list watchers, stop them all. | | `fip`, `dip`, `lip` | Forward remote ports to localhost over SSH, disconnect them, list them. | > ⚠️ **Gotcha**: `format-drive` erases an entire disk. Run it with no arguments first to see the available drives, and read the device name twice. The manual's own advice is "Be careful!" The `fip` function is worth a worked example. Say a dev server runs on port 3000 on a machine you reach as `nyc-dev`: ```bash fip nyc-dev 3000 ``` After that, `localhost:3000` on your laptop reaches `nyc-dev:3000`, which gives browsers the secure-context treatment they give to localhost (needed for testing things like web sockets) without setting up certificates. `lip` lists the forwards and `dip` closes them. For what SSH is doing underneath, see [SSH and Keys](/guides/ssh-and-keys). `ssh` itself is wrapped too. If a connection dies while a remote tmux, Herdr, or editor has the terminal, Omarchy cleans the terminal up and reconnects automatically on an interactive session that drops. `Ctrl + C` stops the retry loop. Your own aliases go in `~/.bashrc`, which the manual says Omarchy does not overwrite on updates. ## Your turn: stop, copy, jump ```exercise [ { "type": "predict", "task": "In a terminal, you run a command that will not stop and press Ctrl + C. What does that key combination do to the program? (One word is enough.)", "accept": ["/interrupt|stop|cancel|sigint|kill|terminate/i"], "hint": "It is not copy. Think of how you stop a runaway command." } ] ``` Check yourself before moving on: ```quiz [ { "q": "Why does Omarchy give you Super + C and Super + V for copy and paste?", "choices": [ "Because Ctrl + C does not work in any Linux app", "Because in a terminal Ctrl + C means interrupt, so terminals and other apps normally need different keys, and Super + C works in both", "Because Foot has no clipboard support" ], "answer": 1, "explain": "Terminals use Ctrl + Shift + C and V because Ctrl + C interrupts the running program. Omarchy's Super keys work the same everywhere.", "why": ["Ctrl + C copies in ordinary apps. Only terminals treat it differently.", null, "Foot has a clipboard; its own copy and paste keys are Ctrl + Shift + C and V."] }, { "q": "You type cd omarchy in a fresh terminal and it fails, but cd ~/.config/omarchy works. Why?", "choices": [ "zoxide only remembers directories you have already visited", "cd with a short name is not allowed", "The directory is hidden" ], "answer": 0, "explain": "zoxide builds its memory from the directories you actually enter. Visit it once with the full path and the short name works afterward." }, { "q": "What does format-drive do?", "choices": [ "Cleans up the current directory", "Formats an entire disk with a single exFAT partition, so you should run it with no arguments first to see the drives", "Mounts a USB stick read-only" ], "answer": 1, "explain": "It erases the whole disk you point it at. The manual warns to be careful." } ] ``` ## Recap 1. Foot is the default terminal. It is fast and has no tabs or splits; tmux covers that, or install Alacritty, Ghostty, or Kitty from _Install > Terminal_. 2. `Super + C` and `Super + V` copy and paste in every app, because `Ctrl + C` in a terminal means interrupt. 3. Omarchy adds `ff`, `Ctrl + R`, zoxide-backed `cd`, `rg`, `fd`, `bat`, `eza` listings, and `tldr`. 4. Helper functions cover archives, drives, Git worktrees, rsync watching, and SSH port forwarding. `format-drive` erases a disk. 5. Put your own aliases and functions in `~/.bashrc`. Next up, [Tmux: Sessions, Windows, and Panes](02-tmux-sessions-windows-and-panes.md): tabs and splits that survive closing the window. --- # Tmux: Sessions, Windows, and Panes You are three hours into a long job in a terminal window, and you close the window by accident. On most setups the job dies with it. Tmux is the tool that makes that impossible: the work runs inside tmux, the window is only a view, and you can close it and come back later. It is also how you get tabs and splits in a terminal that has none, like Foot. ## The model: three nested things Tmux manages **sessions**, which contain **windows**, which contain **panes**. A session is a workspace you can leave and return to. A window is like a browser tab. A pane is one shell, with several panes sharing a window. ```mermaid flowchart TD S["Session: Work"] --> W1["Window 1: editor"] S --> W2["Window 2: server"] W1 --> P1["Pane: nvim"] W1 --> P2["Pane: shell"] ``` Tmux keeps running in the background as its own process. When you close the terminal window, the session carries on. That is the **detach** idea: you leave, it stays. ## Starting and returning Press `Super + Alt + Return`. Omarchy runs `tmux attach || tmux new -s Work`, so you reattach to an existing session if there is one, and otherwise create a session named `Work`. Close that window and press the same keys again, and you are back where you left off. You can do the same from any terminal with the `t` alias. Tmux also works over SSH, so on a remote server you use the same keys you use at home (see [SSH and Keys](/guides/ssh-and-keys)). ## The prefix key Tmux commands start with a **prefix** key so they do not collide with the programs inside. Omarchy's prefix is `Ctrl + Space` (`Ctrl + B`, the tmux default, also works). Press and release the prefix, then press the command key. This guide writes that as `Prefix + s`. The status bar at the top of the screen shows `PREFIX` while tmux is waiting for the next key, `COPY` in copy mode, and `ZOOM` when a pane is zoomed. If tmux seems stuck, that bar tells you what state it is in. ## The keys worth learning first Omarchy's tmux config is tuned for ergonomics, so many common actions have a no-prefix shortcut with `Alt`. | Do this | With prefix | Without prefix | |---|---|---| | Split side by side | `Prefix + v` | `Alt + Shift + Enter` | | Split top and bottom | `Prefix + h` | `Alt + Enter` | | Close the pane | `Prefix + x` | `Alt + Escape` | | Zoom a pane to full screen (again to restore) | `Prefix + z` | n/a | | Move between panes | n/a | `Ctrl + Alt + Arrows` | | Resize panes | n/a | `Ctrl + Alt + Shift + Arrows` | | New window | `Prefix + c` | n/a | | Go to window 1 to 9 | n/a | `Alt + 1` to `Alt + 9` | | Previous or next window | n/a | `Alt + Arrow Left` or `Right` | | Rename or kill a window | `Prefix + r`, `Prefix + k` | n/a | | List sessions and switch | `Prefix + s` | n/a | | New, rename, kill session | `Prefix + C`, `Prefix + R`, `Prefix + K` | n/a | | Next or previous session | `Prefix + N`, `Prefix + P` | `Alt + Arrow Down` or `Up` | | Detach | `Prefix + d` | n/a | Notice the capital letters: `Prefix + c` makes a window and `Prefix + C` (with Shift) makes a session. Windows are numbered from 1, so `Alt + 1` is the first window. The new splits open in the directory of the pane you split, which saves a lot of `cd`. The mouse is on, so you can click a pane to focus it and scroll with the wheel. ### Copying text Copy mode is vi-style. Press `Prefix + [` to enter it, move with the usual vi motion keys, press `v` to start a selection and `y` to copy it. If you do not know vi keys, [Editing in the Terminal](/guides/editing-in-the-terminal) teaches them, and the same keys work in Neovim in [Phase 3](03-neovim-the-omarchy-way.md). ### Help is built in - `Prefix + ?` shows tmux's keybindings in a popup. - `Super + Alt + K` shows an annotated, searchable list from anywhere. - `Prefix + :` opens the tmux command prompt. - `Prefix + q` reloads `~/.config/tmux/tmux.conf` after you edit it. If you break the config, _Update > Config > Tmux_ restores Omarchy's version and reloads tmux (see [Making Omarchy Comfortable](/guides/making-omarchy-comfortable)). ## Dev layouts: tdl and friends Omarchy ships four shell functions that build a multi-pane workspace in one command. They only work inside tmux. Run `tdl` in a plain terminal and it stops with `You must start tmux to use tdl.` | Command | Layout | |---|---| | `tdl []` | Editor on the left (`$EDITOR .`), an AI agent on the right, a terminal along the bottom | | `tds` | Four-way square: editor, a live diff watcher (`hunk diff --watch`), a terminal, and opencode | | `tdlm ` | One `tdl` window for every subdirectory of the current directory | | `tsl ` | A grid of panes all running the same command | ```text tdl c +---------------------------+----------+ | | | | editor (nvim .) | agent | | | | +---------------------------+----------+ | terminal | +--------------------------------------+ ``` `tdl` also renames the window after the current directory. With `tdlm`, move between the per-project windows with `Alt + 1`, `Alt + 2`, and so on. The shortcuts are `ic` for `tdl c`, `ix` for `tdl cx`, and `icx` for `tdl c cx`. The right-hand pane runs whatever command you pass, so the layouts are built for AI agents but you decide what goes in them. `tsl 4 c` gives you a four-pane grid of the `c` agent. > ⚠️ **Gotcha**: the short agent aliases start agents in their auto-approve modes (`c` is `opencode --auto`, `cx` is Claude Code with `--permission-mode auto`, and `cy` is `codex --approve-for-me`). Omarchy's manual says so explicitly. Use them in projects where you are comfortable letting the agent act, and see [AI in the Terminal CLIs](/guides/ai-in-the-terminal-clis) for the habits that keep that safe. The same layouts exist for Herdr, Omarchy's other terminal workspace manager, as `hdl`, `hds`, `hdlm`, and `hsl`. Herdr uses the same `Ctrl + Space` prefix, starts with `Super + Ctrl + Return`, and shows its keys on `Super + Ctrl + K`. ## Your turn: build a workspace ```exercise [ { "type": "task", "task": "Prove the session survives. Open tmux, start something long-running, close the window, and get it back.", "reveal": "1) Super + Alt + Return. 2) Run something long, such as btop or sleep 600. 3) Close the terminal window with Super + W. 4) Press Super + Alt + Return again: it reattaches and the program is still running.", "checklist": ["I split a pane with Alt + Enter", "I made a second window with Prefix + c and jumped back with Alt + 1", "I closed the terminal window and reattached with Super + Alt + Return", "I checked the keys with Prefix + ?"] } ] ``` Check yourself before moving on: ```quiz [ { "q": "You close the terminal window while a command is running inside tmux. What happens to the command?", "choices": [ "It stops, because its window is gone", "It keeps running in the tmux session, and Super + Alt + Return reattaches to it", "It restarts from the beginning" ], "answer": 1, "explain": "Tmux runs as its own background process. Closing the window only detaches you from the session.", "why": ["That is what happens without tmux. Tmux sessions outlive the window.", null, "Nothing restarts. The program carries on where it was."] }, { "q": "Which key splits the current pane into two side-by-side panes with no prefix?", "choices": [ "Alt + Enter", "Alt + Shift + Enter", "Ctrl + Alt + Arrows" ], "answer": 1, "explain": "Alt + Shift + Enter splits beside. Alt + Enter splits below, and Ctrl + Alt + Arrows moves between panes.", "why": ["That splits the pane top and bottom.", null, "That moves focus between panes; it does not split."] }, { "q": "You run tdl c in a plain terminal that is not inside tmux. What happens?", "choices": [ "It starts tmux for you and builds the layout", "It stops with a message that you must start tmux first", "It builds the layout using Foot splits" ], "answer": 1, "explain": "The layout functions check for a tmux session and refuse to run outside one. Start tmux with Super + Alt + Return first." } ] ``` ## Recap 1. Tmux has sessions, which contain windows, which contain panes. Sessions outlive the terminal window. 2. `Super + Alt + Return` attaches to your session or creates one named `Work`. 3. The prefix is `Ctrl + Space`. The no-prefix `Alt` shortcuts cover splits (`Alt + Enter`, `Alt + Shift + Enter`), pane focus (`Ctrl + Alt + Arrows`), and windows (`Alt + 1` to `9`). 4. `Prefix + ?` and `Super + Alt + K` show every key; `Prefix + q` reloads the config. 5. `tdl`, `tds`, `tdlm`, and `tsl` build dev layouts, but only inside tmux. The `c`, `cx`, and `cy` agent aliases run in auto-approve modes. Next up, [Neovim the Omarchy Way](03-neovim-the-omarchy-way.md): the editor that fills the left pane of `tdl`. --- # Neovim the Omarchy Way You open Omarchy's editor, type a few letters, and the cursor jumps around instead of inserting text. That is not a bug. Neovim is a modal editor, and Omarchy ships it fully set up so that a few memorized keys give you a file finder, a search, a file tree, and Git inside the editor. The payoff is large and the learning curve is real, so this phase gives you the smallest path through it. ## What you actually get Omarchy installs Neovim as the default editor with the `omarchy-nvim` package, built on [LazyVim](https://www.lazyvim.org/), a curated collection of Neovim plugins and settings. You do not write any configuration for it to work. Switching your Omarchy theme also restyles the editor, because a theme covers Neovim. Start it any of these ways: - Type `n` in a terminal. It is an alias for `nvim`, and with no argument it opens the current directory. `n myfile.txt` opens one file. - Press `Super + Shift + N` to launch your default editor from anywhere. - Run a `tdl` layout from [Phase 2](02-tmux-sessions-windows-and-panes.md), which opens it for you in the left pane. ## The three keys that save you Neovim starts in **normal mode**, where letter keys are commands rather than text. That is why typing "moves the cursor around". Three keys get you out of every corner: | Key | What it does | |---|---| | `i` | Enter insert mode, where typing inserts text | | `Esc` | Back to normal mode | | `:wq` then `Enter` | Save and quit (`:q!` quits without saving) | That is survival. The full mental model, including how to quit without panic, is in [Editing in the Terminal](/guides/editing-in-the-terminal). For learning vim properly, the Omarchy manual recommends ThePrimeagen's "Vim As Your Editor" series on YouTube, and it is straight about the trade: vim takes longer to become proficient in than a mainstream editor, and the payoff is also larger. ## The leader key: Space LazyVim's **leader key** is `Space`. It is the doorway to nearly every command. Press it, wait a second, and a menu appears showing what each next key does, so you can discover commands instead of memorizing them. The commands the manual says it uses all the time: | Keys | What it does | |---|---| | `Space Space` | Fuzzy-find any file in the current directory | | `Space S G` | Search the contents of all files with grep, with a preview | | `Space E` | Toggle the file tree | | `Ctrl + W W` | Hop between the file tree and the editor | | `Shift + H` and `Shift + L` | Move to the tab on the left or right (vim calls them buffers) | | `Space B D` | Close the current tab | | `Space B O` | Close all other tabs | | `Space G G` | Open LazyGit in a floating pane | | `Space U W` | Toggle soft wrap | The file finder and the search are the same fzf and ripgrep tools from [Phase 1](01-your-terminal-and-shell-toolkit.md), so what you learned at the shell prompt carries over. In the file tree (`Space E` to open, `Ctrl + W W` to jump into it), press `a` to add a file, `A` to add a directory, and `?` to see every command. > 💡 **Key point**: you do not have to memorize LazyVim. Press `Space` and read. When you want the full list, _Learn > Neovim_ in the Omarchy menu opens the [LazyVim keymaps page](https://www.lazyvim.org/keymaps). ## Git without leaving the editor `Space G G` opens LazyGit in a floating pane over your code. LazyGit is a terminal Git interface you will meet again in [Phase 4](04-tuis-and-development-tools.md). If Git commands themselves are new, [Git From Zero](/guides/git-from-zero) explains what you are looking at. ## Editing files only root can change Some files, like those under `/etc`, belong to root. Skip `sudo nvim` for these. The manual's approach keeps all your plugins: ```bash sudoedit /etc/sudoers.d/00-sudo-only-file ``` *What just happened:* `sudoedit` opens a copy of the file in your normal editor with your normal config, then writes it back with elevated privileges when you save. ## Prefer a different editor Neovim is the default, not a requirement. Open the Omarchy menu (`Super + Space`) and look under _Install > Editor_: VSCode, Cursor, Zed, Sublime Text, Helix, Vim, and Emacs are listed. If your editor is not there, try _Install > Package_, and then _Install > AUR_. Set the system-wide default under _Setup > Defaults > Editor_, or run `omarchy default editor code`. Theme matching is offered for VSCode, Cursor, VSCodium, and Helix. > ⚠️ **Gotcha**: `omarchy reinstall configs` (the drastic reset from [Making Omarchy Comfortable](/guides/making-omarchy-comfortable)) also refreshes the Neovim setup, according to the script that implements it. If you have added your own Neovim customizations, back them up before using it. ## Your turn: three keystrokes ```exercise [ { "type": "predict", "task": "In Neovim on Omarchy, which key sequence (leader key plus keys) opens the fuzzy file finder? Type the keys separated by spaces, for example: Space A B.", "accept": ["/^space\\s+space$/i"], "hint": "The leader key twice." }, { "type": "predict", "task": "Which key sequence toggles the file tree? Type it the same way.", "accept": ["/^space\\s+e$/i"], "hint": "Leader key, then the first letter of Explorer." } ] ``` Check yourself before moving on: ```quiz [ { "q": "You open a file in Neovim, type some letters, and the cursor jumps around instead of inserting text. What is happening?", "choices": [ "The file is read-only", "You are in normal mode, where letter keys are commands; press i to insert text", "Neovim is frozen" ], "answer": 1, "explain": "Neovim starts in normal mode. Press i to insert, Esc to return, and :wq to save and quit.", "why": ["A read-only file would give you a warning, not cursor movement.", null, "It is responding to your keys as commands."] }, { "q": "Which key sequence opens LazyGit in a floating pane from inside Neovim?", "choices": [ "Space G G", "Space E", "Ctrl + W W" ], "answer": 0, "explain": "Space G G launches LazyGit. Space E toggles the file tree and Ctrl + W W hops between tree and editor." }, { "q": "You need to edit a root-owned file and keep your Neovim setup. What does the manual suggest?", "choices": [ "Log in as root and run nvim", "Run sudoedit on the file", "Change the file's permissions to 777" ], "answer": 1, "explain": "sudoedit edits a copy with your own editor and config, then writes it back with elevated privileges.", "why": ["A root session would not have your plugins and settings.", null, "Loosening permissions on system files is unsafe and is not what the manual suggests."] } ] ``` ## Recap 1. Omarchy's Neovim is the `omarchy-nvim` package built on LazyVim, themed with your Omarchy theme and ready without configuration. 2. Start it with `n`, or `Super + Shift + N` for your default editor. 3. Normal mode first: `i` to type, `Esc` to stop, `:wq` to save and quit. 4. `Space` is the leader key. Learn `Space Space`, `Space S G`, `Space E`, and `Space G G` first. 5. Use `sudoedit` for root-owned files, and install other editors from _Install > Editor_ if you prefer them. Next up, [TUIs and Development Tools](04-tuis-and-development-tools.md): lazygit, lazydocker, mise, Docker, and databases. --- # TUIs and Development Tools A TUI is a terminal user interface: a full-screen app that runs in the terminal and takes keyboard input. Omarchy ships several, and they cover jobs that usually need a separate GUI. The same menu installs your languages and gets Docker running. This phase covers both, with the decisions Omarchy made for you, including the one that surprises people: Docker needs `sudo` by default. ## The TUIs that ship with Omarchy | App | Start it | What it is for | |---|---|---| | Lazygit | `lazygit` in a Git repo, or `Space G G` in Neovim | Drive Git with a keyboard interface | | Lazydocker | `Super + Shift + D` | See and manage containers and images | | Btop (called Activity) | `Super + Ctrl + T` | Watch CPU, memory, disk, network, and processes | | Herdr | `Super + Ctrl + Return` | Terminal workspaces with sessions you can detach from | | Fastfetch (called About) | _About_ in the Omarchy menu | System information | | Disk Usage | _Disk Usage_ in the launcher (`Super + Space`) | Find what fills the drive and delete from inside it | | Cliamp | `Super + Shift + Alt + M` | A retro terminal music player | Each shows its own keys with `?`. A few worth knowing: - **Lazygit**: `Tab` hops between panes. In the Files pane, `Space` stages a file and `c` starts a commit. [Git From Zero](/guides/git-from-zero) explains the staging and committing it shows. - **Lazydocker**: `s` stops a container and `r` starts or restarts it. - **Btop**: it opens as a floating window. Press `Super + T` to tile it. To understand what the numbers mean, read [Processes, Memory, and CPU](/guides/processes-memory-and-cpu). - **Disk Usage** is `dua` in interactive mode, pointed at the whole file system. It sorts the biggest first and lets you walk down into the culprit. Wi-Fi and Bluetooth have no TUI. Click the bar icon or use `Super + Ctrl + W` and `Super + Ctrl + B`. Any terminal program can become a launcher entry. Open _Install > TUI_, give it a name, a launch command, a window style, and an icon, and it appears in the app launcher. Remove it again under _Remove > TUI_. ## Languages and versions with mise Omarchy sets up development environments from _Install > Development_ in the Omarchy menu. The list covers Ruby on Rails, JavaScript (Node.js, Bun, Deno), PHP with Laravel or Symfony, Go, Rust, Python, Java, Elixir with Phoenix, .NET, OCaml, Zig, Clojure, and Scala. Most are managed by [mise](https://mise.jdx.dev/), a tool for installing and running several versions of a language on one machine. It plays the role that rbenv does for Ruby or virtualenv does for Python, across many languages. The two commands you need: ```bash mise use -g ruby mise i ``` *What just happened:* the first installs Ruby and makes it the global default (`-g`). The second, run in a project folder that has a `.ruby-version` file, installs the version that project asks for. Replace `ruby` with the language you want. Reading the install scripts shipped with 4.0.4, a few environments use the language's own installer instead of mise: Rust installs through rustup, OCaml through opam, and Python installs through mise but also adds [uv](https://docs.astral.sh/uv/). [Python Packaging: pip, Poetry, and uv](/guides/python-packaging-pip-poetry-uv) covers what that gives you. `omarchy update` keeps the mise-managed tools current, and the `mup` alias updates them on their own. ## Docker, and why it needs sudo Omarchy installs Docker and Docker Compose, and then makes one deliberate choice. Your user is **not** in the `docker` group by default. Membership in that group is effectively passwordless root, because anything in it can run a container that mounts the whole disk and takes over the machine, so a single rogue script or dependency running as you would be one command from root. So on the command line, you use `sudo`: ```bash sudo docker ps sudo docker compose up ``` The graphical tools, Lazydocker on `Super + Shift + D` and the Windows VM, ask for authorization instead; Lazydocker prompts the first time. If you understand the tradeoff and want plain `docker` back, enable it from _Setup > Security > Sudoless Docker_ (or `omarchy-setup-security-sudoless-docker`). It shows a warning, then adds you to the group, and takes effect after a reboot. After that, `docker` and its `d` alias work without `sudo`. For what containers are and how Compose files work, see [Docker Without the Magic](/guides/docker-without-the-magic) and [Docker Compose for Real Projects](/guides/docker-compose-for-real-projects). ### Databases in one menu click _Install > Development > Docker DB_ starts a database in a container. The choices are MySQL, PostgreSQL, Redis, MongoDB, MariaDB, and MSSQL. From the install script: - Each container is published only on `127.0.0.1`, so it is reachable from your machine and not from the network. - Each is started with `--restart unless-stopped`, so it comes back after a reboot. - Ports are the standard ones (PostgreSQL 5432, Redis 6379, MongoDB 27017, and so on). MySQL and MariaDB both use 3306, so you cannot run both at once. - The setups are for local development: the PostgreSQL container, for example, accepts connections without a password. > ⚠️ **Gotcha**: those development defaults are only safe because of the `127.0.0.1` binding. Never publish one of these containers on a public address with its default credentials. ## GitHub and AI agents `gh`, the GitHub command-line tool, is a lazy stub: the first time you run it, it installs itself. Then `gh auth login` signs you in, and `gh repo clone org/repo` clones private repositories. Lazygit is preinstalled, and a `ghui` stub gives you a pull-request TUI. Omarchy also pre-wires the major coding-agent command-line tools (`claude`, `codex`, `opencode`, `gemini`, `copilot`, and others) as lazy stubs in `~/.local/bin`. Nothing downloads until you first run one. Pick a default under _Setup > Defaults > Agent_ or with `omarchy default agent `, launch it with `Super + Shift + Ctrl + A`, or run `a` for it inline. Agents started this way run in their don't-stop-to-ask modes, as covered in [Phase 2](02-tmux-sessions-windows-and-panes.md). For the habits that keep that useful, read [AI in the Terminal CLIs](/guides/ai-in-the-terminal-clis). ## Your turn: Docker the Omarchy way ```exercise [ { "type": "predict", "task": "On a default Omarchy install (not in the docker group), type the command that lists running containers.", "accept": ["/^sudo\\s+docker\\s+ps$/i"], "hint": "It is the usual Docker command, with the privilege prefix Omarchy's default requires." } ] ``` Check yourself before moving on: ```quiz [ { "q": "Why does Omarchy not add your user to the docker group by default?", "choices": [ "Docker does not work with groups", "Membership in that group is effectively passwordless root, so any script running as you could take over the machine", "To save disk space" ], "answer": 1, "explain": "A user in the docker group can run a container that mounts the whole disk. Omarchy keeps you out of it, so docker commands need sudo, unless you opt in under Setup > Security > Sudoless Docker.", "why": ["Docker uses a group; that is the problem Omarchy is avoiding.", null, "Disk space is not the reason."] }, { "q": "You run mise i inside a project folder that contains a .ruby-version file. What does it do?", "choices": [ "Installs the version of Ruby that the project asks for", "Deletes your global Ruby", "Updates Omarchy" ], "answer": 0, "explain": "mise reads the project's version file and installs what it names. mise use -g sets a global default instead." }, { "q": "You install PostgreSQL from Install > Development > Docker DB. Who can connect to it?", "choices": [ "Anyone on your network", "Only programs on your own machine, because the container is published on 127.0.0.1", "Only after you set a password" ], "answer": 1, "explain": "The install script publishes it on 127.0.0.1, which is why its development defaults (no password) are tolerable. Never expose it publicly with those defaults." } ] ``` ## Recap 1. Omarchy ships TUIs for Git (`lazygit`), containers (`Super + Shift + D`), and system monitoring (`Super + Ctrl + T`), and you can add your own under _Install > TUI_. 2. Install languages from _Install > Development_. Most use mise: `mise use -g ` for a global default, `mise i` for a project's pinned version. 3. Docker is installed, but your user is not in the `docker` group, so use `sudo docker ...` or opt in under _Setup > Security > Sudoless Docker_. 4. _Install > Development > Docker DB_ runs MySQL, PostgreSQL, Redis, MongoDB, MariaDB, or MSSQL on `127.0.0.1` with local-development defaults. 5. `gh` and the coding agents are lazy stubs that install on first run; the agent aliases run in auto-approve modes. That completes the toolkit. To keep it all current, see [Installing and Updating Software on Omarchy](/guides/installing-and-updating-software-on-omarchy), and for when something stops working, [When Omarchy Breaks](/guides/when-omarchy-breaks).