Command Line Interface (CLI)

Command Book includes a CLI that lets you run, list, create, and edit saved commands directly from your terminal. Define a command once in Command Book and execute it from either the GUI or CLI.

# Run a saved command
$ commandbook run talk-python-dev

# List all saved commands
$ commandbook list

# Create a new command interactively
$ commandbook new

# Edit an existing command
$ commandbook edit talk-python-dev

# Open the GUI app
$ commandbook open

Why a CLI?

Command Book's GUI lets you configure commands with precision: working directories, pre-commands, environment variables, auto-restart behavior, and more. The CLI brings all of that to your terminal with zero extra setup.

When you run commandbook run <command-name>, the CLI executes the command exactly as if you clicked Run in the GUI. It reads the same saved configuration and replicates every detail:

• Working directory -- cds to the configured path before execution
• Pre-commands -- Runs setup steps (like git pull) before the main command
• Environment variables -- Applies any configured env vars to the process
• Auto-restart -- Restarts on crash with the same delay you set in the GUI
• Login shell -- Uses your shell's PATH, aliases, and environment

Instead of remembering cd ~/projects/talk-python && git pull && python app.py --reload, you run:

$ commandbook run talk-python-dev

One command, fully configured, every time. Define it once in Command Book, run it from wherever you prefer -- the GUI or the terminal.

The CLI also opens the door to automation and integration. Shell scripts, CI pipelines, Claude Code, and other agentic coding tools can all invoke your saved commands with commandbook run. Your carefully configured commands become accessible to any tool that can call a shell command.

To help your AI agent use the CLI effectively, add https://commandbookapp.com/docs/ai-guide.md to your project's agent instructions (e.g. CLAUDE.md, .cursorrules, or equivalent) -- it's a concise reference written specifically for LLMs.

Installation

The CLI ships inside the Command Book app bundle. Install it from the GUI:

From Settings

1. Open Command Book
2. Go to Settings (⌘,)
3. Select the CLI Tools tab
4. Click Install CLI Tools

From the Menu Bar

1. Open Command Book
2. Click File → Install CLI Tools

What Happens

The installer creates a symlink at ~/.local/bin/commandbook pointing to the CLI binary inside the app bundle. No admin privileges required.

If ~/.local/bin is not in your PATH, Command Book shows instructions to add it:

export PATH="$HOME/.local/bin:$PATH"

Add that line to your ~/.zshrc (or ~/.bashrc), then restart your terminal or run source ~/.zshrc.

Uninstalling

Use Settings → CLI Tools → Remove CLI Tools or File → Remove CLI Tools to remove the symlink.

Commands

commandbook list

Display all saved commands in a formatted table.

$ commandbook list

SLUG                  NAME                    COMMAND
────────────────────────────────────────────────────────────────────────────────
api-server            API Server              npm run dev
docker-postgres       Docker Postgres         docker compose up db
valkey-cache          Valkey Cache            valkey-server
talk-python-dev       Talk Python (dev)       python app.py

Commands are sorted alphabetically by name. If no commands exist, you'll see a message suggesting commandbook new.

commandbook run [slug]

Run a saved command in the foreground, attached to your terminal.

With a slug:

$ commandbook run talk-python-dev

Talk Python (dev)
────────────────────
Pre-command:  git pull
Command:      python app.py --reload
Directory:    ~/projects/talk-python
────────────────────

▶ Running pre-command: git pull
Already up to date.

▶ Running: python app.py
 * Serving Flask app 'app'
 * Running on http://127.0.0.1:5000
^C
Interrupted.

Without a slug (interactive picker):

$ commandbook run

Select a command to run:

  1) API Server              npm run dev
  2) Docker Postgres         docker compose up db
  3) Redis Cache             redis-server
  4) Talk Python (dev)       python app.py

Enter number (1-4): 4

Options:

Behavior:

• Prints a header with the command name, working directory, and configuration
• Streams output to your terminal in real-time with full ANSI color support
• Runs through your login shell, so your PATH, aliases, and environment are available
• If the command has auto-restart enabled and crashes (non-zero exit), the CLI restarts it automatically after the configured delay
• Ctrl+C sends SIGINT to the child process (intentional stop, no auto-restart)
• Exit code matches the child process exit code

Pre-commands run before the main command. If a pre-command fails (non-zero exit), the main command does not start.

commandbook new

Create a new command interactively.

$ commandbook new

Create a new command
────────────────────

Name: Talk Python (dev)
Command: python app.py
Working directory [/Users/you/projects/talk-python]: ~/projects/talk-python
Pre-command (optional): git pull
Auto-restart on crash? (y/N): y

✓ Command 'talk-python-dev' created successfully.

Prompts:

1. Name (required) -- Display name for the command
2. Command (required) -- The shell command to run
3. Working directory (optional) -- Defaults to current directory
4. Pre-command (optional) -- Runs before the main command each time
5. Auto-restart on crash (optional) -- Defaults to No
6. Auto-restart delay (if auto-restart is yes) -- Seconds, defaults to 5

The CLI validates that command executables exist in your PATH and warns (but still allows saving) if they're not found:

Command: assetbuilder --run build_assets.py && python app.py --reload
⚠ Warning: 'assetbuilder' not found in PATH. The command may fail at runtime.

commandbook edit <slug>

Edit an existing command interactively. Current values are shown in brackets -- press Enter to keep them.

$ commandbook edit talk-python-dev

Edit command: Talk Python (dev)
────────────────────────────────

Name [Talk Python (dev)]: Talk Python (development)
Command [python app.py]: python -m flask run
Working directory [~/projects/talk-python]:
Pre-command [git pull]:
Auto-restart on crash? (y/N) [n]: y
Auto-restart delay (seconds) [5]: 3

✓ Command 'talk-python-development' updated successfully.

If the name changes and the slug would change, the CLI confirms:

⚠ Slug will change: talk-python-dev → talk-python-development
Proceed? (Y/n):

commandbook open

Open the Command Book GUI application.

$ commandbook open
Opening Command Book...

If Command Book is already running, it brings the window to the foreground.

commandbook --help

Show help for all commands.

$ commandbook --help

Command Book CLI - Run saved commands from your terminal

USAGE:
    commandbook <command> [options]

COMMANDS:
    list            List all saved commands
    run [slug]      Run a saved command (interactive picker if no slug)
    new             Create a new command
    edit <slug>     Edit an existing command
    open            Open the GUI app

OPTIONS:
    --help          Show this help message
    --version       Show version information

commandbook --version

Show the version number (matches the GUI app version).

$ commandbook --version
Command Book 1.0.0

Slugs

Slugs are URL-style identifiers generated from command names. They're how you reference commands in the CLI.

Slugs are always unique. If two commands would produce the same slug, a numeric suffix is appended: talk-python-dev, talk-python-dev-2, talk-python-dev-3.

Use commandbook list to see all slugs.

Shared Database

The CLI and GUI share the same SQLite database. Commands you create in the GUI appear in commandbook list, and commands you create with commandbook new appear in the GUI. Changes in either are immediately visible to the other.

The database location follows the GUI's storage settings. The storage location is shown in Settings → Storage, the CLI uses the same path.

Troubleshooting

PATH: commandbook: command not found

The CLI is installed at ~/.local/bin/commandbook. If your shell doesn't find it, add ~/.local/bin to your PATH:

# Add to ~/.zshrc or ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"

Then restart your terminal or run source ~/.zshrc.

You can verify the install in Settings → CLI Tools, which shows the PATH status.

Database Not Found

Error: Command Book database not found. Please run the app first to initialize.

This means the CLI can't find the SQLite database. Open Command Book at least once to create it. If you've moved the database via Settings → Storage, the CLI reads the same setting automatically.

Command Not Found (Slug)

Error: Command 'foo' not found. Run 'commandbook list' to see available commands.

Check the exact slug with commandbook list. Slugs are generated from command names and may differ from what you expect (e.g., "My API Server" becomes my-api-server).

Working Directory Doesn't Exist

Error: Working directory '/path/to/dir' does not exist.

The saved working directory has been moved or deleted. Update it with commandbook edit <slug> or use the --dir flag to override:

commandbook run my-command --dir ~/new/path

CLI Not Working After Moving the App

The CLI symlink points to the binary inside the app bundle. If you move Command Book.app to a different location, reinstall the CLI tools from Settings → CLI Tools or File → Install CLI Tools.