CmdBook

Why “cmdbook”?
Because it’s your Command Book – a small notebook where you store the shell commands you actually care about, with tags and descriptions, and recall them in seconds.

CmdBook is a small CLI for storing and retrieving shell commands.
It keeps a local SQLite database with an FTS5 index for fast search. It does not execute commands; it helps you remember, organize, and copy/paste them quickly.

Demo

record.mp4

Features

• Store commands with description, tags, shell, and working directory
• Fast full-text search (command + description) via SQLite FTS5
• Filter by tag
• Mark commands as favorites and list favorites first
• Duplicate detection on add (with --force to override)
• Show a single entry, optionally copy to clipboard
• Edit metadata, delete entries
• Export/Import as JSON for backup or migration
• Simple stats command (total commands, top tags, last added)
• Local-only data (~/.cmdbook/cmdbook.db)

---

Requirements

• Node.js 18, 20, or 22 (recommended)
  better-sqlite3 provides prebuilt binaries for LTS releases; other versions may try to compile from source.
• macOS or Linux (tested). Windows may work via WSL.

---

Installation

Global (recommended)

npm install -g cmdbook

Then:

cmdbook --help

If cmdbook is not found, ensure your global npm bin directory is on PATH or open a new terminal.

From source (development)

git clone https://github.com/doniaskima/CmdBook.git
cd CmdBook
npm install
npm run build
npm link            # makes `cmdbook` available globally

---

Quick Start

# Save commands
cmdbook add "docker system prune -af" -d "Clean Docker garbage" -t docker,cleanup
cmdbook add "git rebase -i HEAD~5" -d "Interactive rebase last 5" -t git

# Mark a favorite
cmdbook fav 1

# List most recent (favorites first)
cmdbook list -n 10
cmdbook list --favorites

# Search (full text over command + description, highlighted)
cmdbook search docker
cmdbook search "interactive rebase" -t git

# Show one and copy to clipboard
cmdbook show 1 --copy

# Edit metadata
cmdbook edit 1 -d "Prune images/containers/networks/volumes" -t docker,cleanup

# Delete, export, import
cmdbook rm 2
cmdbook export > backup.json
cmdbook import backup.json

# Stats
cmdbook stats

---

Command Reference

add <cmd...>

Add a new command.

Options:

• -d, --desc <text>: description
• -t, --tags <docker,git>: comma-separated tags
• -s, --shell <name>: bash|zsh|pwsh|fish (default: bash)
• -c, --cwd <path>: working directory hint
• -f, --force: insert even if the exact same command already exists

Example:

cmdbook add "ssh -i ~/.ssh/key user@host" \
  -d "Prod jumpbox" \
  -t ssh,prod \
  -s bash \
  -c ~/work

If a command with the same text already exists and you don’t pass --force, CmdBook will show the existing entry instead of inserting a duplicate.

---

list

List recent commands.

Options:

• -n, --limit <n>: number of rows (default: 20)
• -t, --tag <tag>: filter by single tag
• -F, --favorites: only show favorites

Favorites are always shown first.

Example:

cmdbook list -n 50
cmdbook list -t docker
cmdbook list --favorites

---

search <q...>

Full-text search across command and description (with highlighted matches).

Options:

• -t, --tag <tag>: filter by tag

Example:

cmdbook search "rebase"
cmdbook search "docker prune" -t docker

---

show <id>

Display a single command.

Options:

• --copy: copy the command text to clipboard

Example:

cmdbook show 3 --copy

---

edit <id>

Update description, tags, shell, or cwd.

Options:

• -d, --desc <text>
• -t, --tags <tags>
• -s, --shell <name>
• -c, --cwd <path>

Example:

cmdbook edit 3 -t docker,cleanup,space -d "Aggressive prune"

---

rm <id>

Delete a command.

cmdbook rm 7

---

fav <id>

Mark a command as favorite (shows with a ★ and sorted first).

cmdbook fav 1

unfav <id>

Remove the favorite mark.

cmdbook unfav 1

---

stats

Show a small summary (count, top tags, last added):

cmdbook stats

---

export

Print all entries as JSON to stdout.

cmdbook export > backup.json

---

import <file>

Import entries from a JSON array (compatible with export).

cmdbook import backup.json

---

Data Location

• Database file: ~/.cmdbook/cmdbook.db

On macOS, open it via:

open ~/.cmdbook

---

Notes on Search

• Full-text search uses SQLite FTS5 over cmd and desc.
• Tag filtering is a simple LIKE filter on the normalized comma-separated string.
• Search terms are highlighted in both command and description.

---

Troubleshooting

• better-sqlite3 build errors on uncommon Node versions:

  • Prefer Node 18/20/22 via nvm.
  • If compiling, ensure build tools are installed (Xcode Command Line Tools on macOS).

• Global command not found after install/link:

  • Confirm the global npm bin directory is on your PATH:

    npm bin -g
    which cmdbook

  • Open a new shell to refresh PATH.

---

Security and Privacy

• All data is stored locally. No network or telemetry is used.
• Exported backups are plain JSON; treat them like any other sensitive notes.

---

Development

• Build: npm run build
• Local run: npm run dev
• Watch dev: npm run dev:watch

MIT license – see LICENSE for details.