👻 NeoHtop CLI

March 29, 2026 · View on GitHub

👻 NeoHtop CLI

A cross-platform terminal process monitor with btop-style visualizations

The CLI companion to NeoHtop — built with Go and the Charm ecosystem.

Installation · Features · Keybindings · Themes · Configuration

Installation

npm install -g neohtop-cli

Or download a prebuilt binary from the Releases page:

macOS

# Apple Silicon
curl -LO https://github.com/Abdenasser/neohtop-cli/releases/latest/download/neohtop-cli-macos-arm64.tar.gz
tar xzf neohtop-cli-macos-arm64.tar.gz
sudo mv neohtop-cli-macos-arm64 /usr/local/bin/neohtop-cli

# Intel
curl -LO https://github.com/Abdenasser/neohtop-cli/releases/latest/download/neohtop-cli-macos-amd64.tar.gz
tar xzf neohtop-cli-macos-amd64.tar.gz
sudo mv neohtop-cli-macos-amd64 /usr/local/bin/neohtop-cli

Linux

# x86_64
curl -LO https://github.com/Abdenasser/neohtop-cli/releases/latest/download/neohtop-cli-linux-amd64.tar.gz
tar xzf neohtop-cli-linux-amd64.tar.gz
sudo mv neohtop-cli-linux-amd64 /usr/local/bin/neohtop-cli

# ARM64
curl -LO https://github.com/Abdenasser/neohtop-cli/releases/latest/download/neohtop-cli-linux-arm64.tar.gz
tar xzf neohtop-cli-linux-arm64.tar.gz
sudo mv neohtop-cli-linux-arm64 /usr/local/bin/neohtop-cli

Windows

Download neohtop-cli-windows-amd64.zip and add the extracted folder to your PATH.

Build from source

Requires Go 1.25+ and a C compiler for CGo on macOS.

git clone https://github.com/Abdenasser/neohtop-cli.git
cd neohtop-cli
make build
make install  # optional — copies to /usr/local/bin/

Features

Real-time monitoring CPU per-core sparklines, memory, disk I/O, and network stats rendered with braille-dot visualizations	Powerful search Regex-powered filtering with live match highlighting — `^chrome`, `name\|pid`, `\.log$`
15 built-in themes Catppuccin, Dracula, Tokyo Night, Nord, Gruvbox, Synthwave, and more — switch with `t`	Process management Inspect details, kill processes, pin favorites to the top, toggle tree view
JSON output `neohtop-cli --json` pipes structured data to `jq` for scripting and dashboards	Single binary, cross-platform macOS, Linux, and Windows — no runtime dependencies

Quick Start

neohtop-cli          # launch the TUI
neohtop-cli --json   # one-shot JSON snapshot
neohtop-cli --help   # see all options

Press ? inside the TUI to see every keybinding.

Keybindings

	Key	Action
General	`q` · `Ctrl+C`	Quit
	`?`	Help overlay
	`s` · `/`	Search (regex)
	`Space`	Pause / resume
	`Esc`	Close overlay / clear search
Navigate	`↑` `↓` `j` `k`	Move selection
	`PgUp` · `PgDn`	Page scroll
	`Home` · `g` / `End` · `G`	Jump to top / bottom
Process	`i` · `Enter`	Inspect details
	`k` · `x` · `Del`	Kill (with confirmation)
	`p`	Pin / unpin
Display	`0`–`9`	Sort by column
	`f`	Filter panel
	`c`	Column visibility
	`T`	Tree view
	`t`	Theme selector
	`r`	Cycle refresh rate
Mouse	Click row	Select process
	Double-click	Open details
	Click header	Sort by column
	Scroll wheel	Navigate list

Search

Press s or / to search. Supports full regex:

chrome          process name contains "chrome"
^sys            names starting with "sys"
\.log$          commands ending in ".log"
node|deno       matches either
1234            PID 1234

Matches are highlighted in yellow in the Name and Command columns.

Themes

Press t to open the theme selector with live color swatches.


Charm (default)	Catppuccin Mocha	Catppuccin Latte
Dracula	Tokyo Night	Gruvbox Dark
Nord	One Dark	Rosé Pine
Synthwave	Solarized Dark	Monokai Pro
High Contrast	Green Terminal	Amber Terminal

JSON Output

--json outputs a single snapshot of system stats and all processes. Perfect for scripting:

# top 10 by CPU
neohtop-cli --json | jq '[.processes[] | {name, cpu: .cpu_usage}] | sort_by(.cpu) | reverse[:10]'

# memory usage
neohtop-cli --json | jq '.system | {memory_used, memory_total, pct: (.memory_used/.memory_total*100|round)}'

# watch mode
watch -n2 'neohtop-cli --json | jq ".system.cpu_usage_per_core"'

Configuration

Settings persist at ~/.config/neohtop-cli/config.json:

{
  "columns": ["pid", "name", "cpu", "memory", "status", "user", "command"],
  "refresh_rate_ms": 1000,
  "theme": "charm"
}

Columns: pid name cpu memory status user command threads runtime disk

Refresh rates — cycle with r: 1s (default) → 2s → 3s → 5s → 0.5s

Architecture

Pure Go application using native OS APIs — no FFI, no external dependencies.

┌──────────────────────────────────────────┐
│          Go TUI (Bubble Tea v2)          │
│                                          │
│  Stats Bar · Toolbar · Process Table     │
│  Sparklines · Braille Bars · Overlays    │
├──────────────────────────────────────────┤
│          Native Go Monitor               │
│                                          │
│  process_darwin.go   system_darwin.go    │
│  process_linux.go    system_linux.go     │
│  process_windows.go  system_windows.go   │
└──────────────────────────────────────────┘

Built with Bubble Tea v2 and Lip Gloss v2.

Project structure

neohtop-cli/
├── cli/
│   ├── main.go               # entry point + --json + --version
│   ├── model/                 # Bubble Tea model (state + update loop)
│   ├── view/                  # UI components
│   │   ├── stats_bar.go       #   CPU, memory, network, info panels
│   │   ├── process_table.go   #   main data grid
│   │   ├── toolbar.go         #   button bar
│   │   ├── footer.go          #   status bar
│   │   ├── sparkline.go       #   time-series sparklines
│   │   ├── bar.go             #   braille progress bars
│   │   ├── help.go            #   keybinding overlay
│   │   ├── process_details.go #   process info modal
│   │   ├── kill_confirm.go    #   kill confirmation
│   │   ├── filter_panel.go    #   filter configuration
│   │   ├── column_panel.go    #   column visibility
│   │   ├── theme_panel.go     #   theme selector
│   │   └── process_icons.go   #   140+ Nerd Font icons
│   ├── monitor/               # OS-specific system monitoring
│   ├── theme/                 # 15 color themes
│   ├── filter/                # search, filter, sort, tree
│   └── config/                # persistent user settings
├── Makefile
└── CONTRIBUTING.md

NeoHtop CLI vs NeoHtop Desktop

Feature	Desktop	CLI
Process monitoring	✅	✅
CPU per-core stats	✅	✅
Memory / Disk / Network	✅	✅
Regex search	✅	✅
Kill / Pin / Inspect	✅	✅
Mouse support	✅	✅
Themes	12	15
Process tree view	—	✅
JSON scripting	—	✅
Runs in terminal	—	✅
Single binary	—	✅

Contributing

See CONTRIBUTING.md for development setup, code style, and how to add themes, icons, and keybindings.

License

MIT

NeoHtop Desktop · Bubble Tea · btop

Made with 👻 by Abdenasser