DEV Community

Yash Ambaskar
Yash Ambaskar

Posted on

I replaced the `man` command with a Python TUI — and it's actually useful

#linux #python #cli #opensource

We've all been there.

You're deep in a terminal session, you forget a flag, so you type man grep — and you're greeted by this:

GREP(1)                   General Commands Manual                   GREP(1)

NAME
     grep, egrep, fgrep, rgrep - print lines that match patterns
...
Enter fullscreen mode Exit fullscreen mode

A wall of monospaced text. No color. No structure. No examples surfaced upfront.

So I built SmartMan CLI — a drop-in, interactive replacement for man that actually respects your eyes and your time.

What it looks like

SmartMan CLI Demo

What it does differently

Feature man smartman
Syntax highlighting ❌ ✅
Interactive sidebar (jump to sections) ❌ ✅
Quick-win examples at the top ❌ ✅
AI-powered plain-English explanations ❌ ✅
Themes (Dracula, Catppuccin, Nord…) ❌ ✅

Features I'm actually proud of

⚡ Quick-Win Gallery

The most painful thing about man pages is that the useful examples are always buried at the bottom.

SmartMan surfaces the most common usage patterns as interactive cards right at the top of every page. No scrolling, no grep-ing through the man page to find what you need.

🤖 AI Explanations (via Groq)

Staring at a complex flag description and still confused? Run:

smartman --explain awk
Enter fullscreen mode Exit fullscreen mode

It hits the Groq API (sub-second response, free tier available) and gives you a plain-English summary of what the command actually does — no more decoding formal specification language at 2am.

📂 Interactive Sidebar

Jump between NAME, SYNOPSIS, DESCRIPTION, OPTIONS, and EXAMPLES instantly using keyboard shortcuts:

Key Action
n Jump to NAME
s Jump to SYNOPSIS
d Jump to DESCRIPTION
o Jump to OPTIONS
e Jump to EXAMPLES
q Quit

🎨 Theming

Built on YAML-based themes, so you can match your exact terminal aesthetic:

  • Default — Modern dark blue
  • Dracula — Classic dev
  • Catppuccin — Pastel mocha
  • Nord — Cool-toned frost
  • Monokai — High-contrast vibrant 
smartman --theme dracula grep
Enter fullscreen mode Exit fullscreen mode

Install it in one line 

curl -sSL https://raw.githubusercontent.com/ambaskaryash/smartman-cli/main/install.sh | bash
Enter fullscreen mode Exit fullscreen mode

Or via pipx if you prefer:

pipx install smartman
Enter fullscreen mode Exit fullscreen mode

Then, to make it your permanent default man command, add this to your .bashrc or .zshrc:

alias man='smartman'
Enter fullscreen mode Exit fullscreen mode

Now every time you type man <command>, you get the full SmartMan experience automatically.

The stack

  • Textual — The TUI framework that makes all the interactive UI possible. If you haven't tried it yet, it's genuinely impressive what you can build in pure Python.
  • Rich — Powers the syntax highlighting and styled rendering.
  • Groq API — For the AI explanations. Chosen specifically for its near-zero latency — it doesn't feel like waiting for an AI.
  • Typer — Clean CLI interface with zero boilerplate.

What's next

  • [ ] Fuzzy search across all installed man pages
  • [ ] Bookmarking frequently-used man pages
  • [ ] --tldr mode (shorter, community-sourced summaries)
  • [ ] Export to PDF

Try it out

The full source code is on GitHub:

👉 github.com/ambaskaryash/smartman-cli

If this saves you even a few seconds of squinting at man pages, a ⭐ on the repo would mean a lot — it helps other Linux users discover it too.

Contributions are very welcome, especially new themes. Adding one is as simple as dropping a YAML file into smartman/themes/.

What's the most annoying thing about the default man command for you? Drop it in the comments — I'm actively looking for what to build next. 👇

Top comments (0)