# super-man

An interactive, fuzzy command + man-page flag browser for the terminal. Search
260+ commands, drill into any one to fuzzy-search its flags with live
descriptions, and jump back to the command list instantly.

## Demo

![super-man demo](demo/super-man-demo.gif)

Video (MP4): [`demo/super-man-demo.mp4`](demo/super-man-demo.mp4) ·
asciinema cast: [`demo/super-man-demo.cast`](demo/super-man-demo.cast)

The clip shows opening an entry (`grep`), browsing its flags, then pressing
**Esc** to return straight to the home screen — no intermediary step — and
repeating with `tar`.

## Usage

```bash
super-man                       # interactive home screen (fzf)
super-man <command> [filter]    # jump straight to a command's flags
super-man -l, --list            # list all known commands
super-man -h, --help            # full help

# Natural-language modes (database-backed, needs jq)
super-man ask "find large files"        # ask a question
super-man task "monitor cpu usage"      # describe what you want to do
super-man category files                # browse by category (files/text/network/system)
super-man explain "tar -czf"            # explain what a command does
super-man ai "count lines in js files"  # AI bash one-liner via local LLM (advanced)
```

### AI mode (local LLM via ollama)

`ai` generates a bash one-liner from plain English using a local [ollama](https://ollama.com)
model. The model is configurable, so you can A/B different local LLMs:

```bash
super-man ai "find python files modified last week"          # default model
super-man ai --model qwen2.5:3b "count lines in all js files"  # override model
super-man ai --compare "list the 5 largest files"             # run several models side by side
```

| Env var | Purpose | Default |
|---------|---------|---------|
| `SUPERMAN_AI_MODEL` | Default model for `ai` | `qwen2.5-coder:1.5b` |
| `SUPERMAN_AI_COMPARE_MODELS` | Space-separated list for `--compare` | `qwen2.5-coder:1.5b westenfelder/NL2SH` |

General coder models (e.g. `qwen2.5-coder`) are prompt-wrapped to emit a single bare
command; the purpose-built `westenfelder/NL2SH` model receives the raw query. Pull
either with `ollama pull <model>`.

`Esc` in the flag browser returns to the command list; `Esc` on the home screen
exits.

**Requirements:** `jq` for the natural-language modes, `fzf` for interactive mode.

See [`docs/`](docs/) for design notes and the full feature history.