Suvadu Home

A searchable map of everything Suvadu can do, grouped by what you want to get done. Find a feature by typing a few words, see the real command behind it, and open it — without leaving the terminal.

Run suv on its own at a terminal to open it; suv home opens it too.

suv

Home is for finding things. Ctrl+R in your shell is still the fastest way to recall a command, and Home never gets in its way.

What you see

On a terminal at least 100 columns wide and 24 rows tall, the list sits beside the details of the selected item. A category lists what each of its features is for; a feature's details come in the same order every time: what it does for you, what opens or happens, the real command, its shortcut, anything it needs, and what Enter will do. On a very large terminal Home keeps to a readable block rather than stretching across the window.

                                             SUVADU HOME
╭ Find a Suvadu feature ───────────────────────────────────────────────────────────────────────────╮
│Try: failed commands, backup, AI prompts                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
Home
╭ Explore ─────────────────────────╮╭ Details ─────────────────────────────────────────────────────╮
│ > Find a command                 ││Find a command                                                │
│   Review a session               ││Search past commands and narrow where to look                 │
│   Organize commands              ││                                                              │
│   Understand my activity         ││Search history              Find and copy a past command      │
│   Review AI activity             ││Commands in this directory  Only what ran in this folder      │
│   Connect tools                  ││Commands in this workspace  Search across the current project │
│   Manage Suvadu                  ││Failed commands             Find commands that failed         │
│   Command reference              ││Print history               A plain list to read or pipe      │
│                                  ││                                                              │
│                                  ││Fast path  Ctrl+R in your shell searches history directly     │
│                                  ││Enter      Browse features                                    │
│                                  ││                                                              │
│                                  ││                                                              │
│                                  ││                                                              │
│                                  ││                                                              │
╰──────────────────────────────────╯╰──────────────────────────────────────────────────────────────╯
Recording: enabled · Capture: not checked · Shell: not paused
 Esc  Quit   Enter  Browse   F1  Keys   Tab  Details   F2  Reference   Ctrl+R  Search history

Home picks one of three layouts from the terminal's size, and redraws as you resize:

Buttons wrap onto more rows rather than being cut off, so the one you are on is always visible.

                         SUVADU HOME
╭ Find a Suvadu feature ───────────────────────────────────╮
│failed                                                    │
╰──────────────────────────────────────────────────────────╯
Features matching “failed” · 1
╭ Results ─────────────────────────────────────────────────╮
│ > Failed commands  picker                                │
│     in Find a command                                    │
│                                                          │
│                                                          │
│                                                          │
│                                                          │
│                                                          │
│                                                          │
│                                                          │
╰──────────────────────────────────────────────────────────╯
Recording: enabled · Capture: not checked
 Esc  Back   Enter  Open search   F1  Keys   Tab  Details

Categories

The Command reference follows the categories: the overview suv --help prints, then every command's own help, generated from the same definitions as the CLI.

Searching for a feature

Typing searches Suvadu's features — never your command history. Every word you type must match the feature's name, command, description or the words people use for it:

An exact name or command ranks first. Clearing the search returns you to the category you were in.

What Enter does — and what it never does

Nothing you open from Home runs a command in your shell. What Enter does depends on the feature, and the details say which it is:

• Screens — settings, sessions, statistics, the alias and skills managers, the agent screens — open exactly as they do from the shell, and Esc brings you back to the same place in Home. A screen that can change your data (the alias manager, settings, skills) says so.
• Pickers — search and bookmarks — show the command you chose with a Copy command button. It has not been run, and Home cannot put it on your prompt; Ctrl+R from your shell does that.
• Reports — recording status, doctor, version, recent history, tags, the agent report — are shown inside Home. They only read.
• Instructions — anything that changes data or your shell: imports, deletion, cleanup, updates, uninstalling, pausing, shell setup, suv wrap. These show what to run in your shell, with copyable examples; <NAME> parts are yours to fill in. Copying an example never runs it.

                              SUVADU HOME
╭ Search history ────────────────────────────────────────────────────╮
│Selected command                                                    │
│git push origin main                                                │
│                                                                    │
│This has not been run.                                              │
│                                                                    │
│Tip: Ctrl+R in your shell puts a selection on the prompt.           │
│                                                                    │
│                                                                    │
│                                                                    │
│                                                                    │
│[ Copy command ]  [ Back to Home ]                                  │
╰────────────────────────────────────────────────────────────────────╯
Recording: enabled · Capture: not checked · Shell: not paused
 Esc  Back   Enter  Copy command   L/R  Choose   Up/Dn  Scroll

Cancelling a picker brings you straight back to Home with a short note. With nothing recorded yet, search cannot open, and Home says so instead.

Some things can only happen in your own shell. eval "$(suv pause)" pauses the shell that runs it, and new aliases reach a shell when it starts; Home explains both rather than pretending to do them.

Keys

A paste only ever adds to the search: a pasted line break becomes a space and never opens anything.

Keeping the classic overview

Since 0.5.0 a bare suv at a terminal opens Home. To have it print the command overview instead, set Startup Screen to help in the Shell tab of suv settings, or put this in your config.toml:

[home]
startup = "help"   # or "home", the default
icons = "ascii"    # or "unicode" for the category markers

• suv home always opens Home, and suv --help always prints the overview, whatever the setting.
• Scripts, pipes and TERM=dumb always get the overview — on stderr with exit status 2, exactly as before — so nothing that runs a bare suv non-interactively changes.
• The setting belongs to you, not the project: only your own config sets it, and a project's .suvadu.toml cannot.
• A choice made in settings opened from Home applies to the next suv; the Home you are in stays open.
• If a terminal cannot be set up for Home, a bare suv prints the overview with the reason instead.

When something is missing or broken

Home needs no database and no valid config to browse, and it writes nothing while you browse. If your config cannot be read, the status line says so and the file is left as it is. The status line shows what the configuration says — recording enabled or disabled, this shell paused or not — and marks capture as not checked: whether commands are really being recorded is what Recording status and Diagnose setup check.

Home honours NO_COLOR, needs no Nerd Font or emoji, and works on macOS and Linux.