cmd — Command Launcher

Fast terminal command launcher with fuzzy search, live output, form inputs, and cwd-aware detection.

Install

npm install -g @dev-belts/core

That's it. The cmd binary is now in your PATH.

cmd                  # open TUI in current terminal
cmd -e               # open command explorer in floating Alacritty (bind to Ctrl+/)
cmd -L btop          # open any app in floating Alacritty
cmd -L lazygit

Features

| Feature | Description | |---|---| | Fuzzy search | Search by name, description, or short alias (code) | | Filter bar | Tab through ALL / LOCAL / NPM / MAKE categories | | Form inputs | Commands can prompt for text, number, password, or choice before running | | CWD-aware | Detects the focused terminal's cwd — commands run there | | Global + local commands | ~/.commands/ global + .commands/ per-project | | NPM scripts | Auto-detects package.json scripts in current directory | | Makefile targets | Auto-detects Makefile targets annotated with ## descriptions | | Live output panel | Background runs stream stdout/stderr inline in the TUI | | System notifications | Desktop notification on command success or failure | | Clipboard | copy: commands put text straight into the clipboard | | Floating launcher | Alfred/Raycast-style with cmd --launcher | | Folder history | Recently opened directories saved to ~/.cmd/folders_history | | Cross-platform | macOS (Hammerspoon) and Linux (Hyprland, X11, Wayland) |

Hotkey Setup

macOS

cmd --setup-keys

This checks for Hammerspoon, installs the Ctrl+/ binding, and reloads the config. If anything is missing, it tells you exactly what to do (and makes it fun).

Hyprland

Add to ~/.config/hypr/hyprland.conf:

bind = CTRL, slash, exec, cmd -e

Other Linux (sxhkd, i3/Sway, GNOME, KDE)

# sxhkd (~/.config/sxhkd/sxhkdrc)
ctrl + slash
    cmd -e

# i3 / Sway
bindsym Ctrl+slash exec cmd -e

The launcher auto-detects available terminals: alacritty → kitty → foot → wezterm → gnome-terminal → konsole → xterm.

Floating window for any app

Use cmd --launcher (or -L) to open any TUI app in a floating Alacritty window:

cmd -L btop
cmd -L lazygit
cmd -L htop
WIDTH=1400 HEIGHT=900 cmd -L htop   # custom window size

Keyboard Shortcuts

Main TUI

| Key | Action | |---|---| | ↑ / ↓ | Navigate the command list | | Tab / Shift+Tab | Next / previous filter category | | Enter | Execute selected command | | Esc or Ctrl+C | Quit |

While a Command is Running

| Key | Action | |---|---| | PgUp / PgDn | Scroll live output panel | | Ctrl+X | Kill the running process | | Esc or Ctrl+C | Quit (process continues detached) |

Input Form (when a command has inputs:)

| Key | Action | |---|---| | Enter | Confirm current field and advance | | ↑ / ↓ | Navigate choices (for choice type) | | Backspace | Delete last character | | Esc | Cancel and return to list |

Confirm Dialog

| Key | Action | |---|---| | Enter | Execute the command | | P | Toggle password visibility | | Esc | Cancel |

Command Format

Commands are YAML files in ~/.commands/ (global) or .commands/ inside any project (local).

name: "My Command"
description: "Optional description shown in the list"
code: "mc"          # short alias for fuzzy search (optional)
run: "echo hello"   # execute in shell  ← mutually exclusive
copy: "some text"   # copy to clipboard ←

Basic Examples

# ~/.commands/gs.yml
name: "Git Status"
description: "Show repo status"
code: gst
run: git status

# ~/.commands/token.yml
name: "Copy API Token"
code: tok
copy: "Bearer eyJhbGci..."

# .commands/deploy.yml  ← local to the project
name: "Deploy"
description: "Build and deploy"
code: dep
run: npm run build && ./deploy.sh

Local commands show a [local] badge and run in the project directory.

Command Inputs

Commands can define interactive inputs using inputs:. Use {{key}} placeholders in run: or copy:.

text — Free text:

name: "SSH into server"
run: "ssh {{host}}"
inputs:
  host:
    type: text
    question: "Hostname or IP?"

number — Digits only:

name: "Repeat echo"
run: "for i in {1..{{count}}}; do echo hello; done"
inputs:
  count:
    type: number
    question: "How many times?"

password — Masked in UI and confirm dialog:

name: "Database dump"
run: "mysqldump -u {{user}} -p{{password}} mydb > backup.sql"
inputs:
  user:
    type: text
    question: "MySQL username?"
  password:
    type: password
    question: "MySQL password?"

choice — Pick from a list (↑↓ to navigate):

name: "Deploy to environment"
run: "ssh {{server}} 'cd /app && git pull'"
inputs:
  server:
    type: choice
    question: "Which server?"
    choices:
      - "production:prod.example.com"   # "label:value" format
      - "staging:stage.example.com"

The label:value format shows production in the UI but substitutes prod.example.com into the command.

Auto-detected Sources

NPM Scripts

When cmd is launched in a directory with package.json, all scripts are loaded automatically. Add descriptions with // scriptname: description comments:

{
  "scripts": {
    "build": "tsc",
    "//build": "Compile TypeScript files",
    "dev": "tsc --watch"
  }
}

These appear with an [npm] badge. Press Tab → NPM to filter.

Makefile Targets

Targets annotated with ## description are auto-loaded:

build: ## Compile the project
	tsc

deploy: ## Deploy to production
	./deploy.sh

These appear with a [make] badge. Press Tab → MAKE to filter.

Filter Bar

Press Tab to cycle through categories. Press Shift+Tab to go backwards.

| Filter | Shows | |---|---| | TODOS | All commands | | LOCAL | Commands from .commands/ in the current project | | NPM | Scripts from package.json | | MAKE | Targets from Makefile |

File Structure

~/.commands/          ← global commands (YAML files)
~/.cmd/
  cache/              ← run output + metadata
    <run-id>/
      stdout          ← captured process output
      meta.json       ← pid, status, exit code, timestamps
  folders_history     ← recently opened directories (max 15)

<project>/
  .commands/          ← local project commands (YAML files)

Platform Support

| Platform | Hotkey | Setup | |---|---|---| | macOS | Ctrl+/ via Hammerspoon | cmd --setup-keys | | Hyprland | bind = CTRL, slash, exec, cmd -e | Edit hyprland.conf | | Linux X11 | sxhkd / KDE / GNOME shortcuts | Edit config file |