# Command Book CLI — AI Agent Reference

Command Book is a macOS app for managing long-running terminal commands. The CLI lets you run saved commands from the terminal. Commands are configured once (name, shell command, working directory, pre-commands, env vars, auto-restart) and executed identically every time.

The CLI and GUI share the same SQLite database. Changes in either are immediately visible to the other.

## Quick Reference

```
commandbook list              # Show all saved commands (slug, name, command)
commandbook run <slug>        # Run a saved command in the foreground
commandbook run               # Interactive picker (requires stdin)
commandbook run <slug> --dir <path>  # Override working directory
commandbook new               # Create a command (interactive, requires stdin)
commandbook edit <slug>       # Edit a command (interactive, requires stdin)
commandbook open              # Open the GUI app
commandbook --version         # Show version
```

## Listing Commands

`commandbook list` prints a table of all saved commands. Use this to discover available slugs.

```
$ commandbook list

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

## Running Commands

`commandbook run <slug>` runs the command in the foreground, attached to your terminal. Output streams in real-time with ANSI color support. The process runs through the user's login shell with their full PATH and environment.

Execution order: pre-commands run first (failure aborts), then the main command.

The exit code matches the child process exit code. If auto-restart is enabled and the process crashes (non-zero exit), the CLI restarts it automatically. Ctrl+C sends SIGINT and does **not** trigger auto-restart.

## Slugs

Slugs are generated from command names: `Talk Python (dev)` → `talk-python-dev`. Always use `commandbook list` to get exact slugs rather than guessing.

## Important for AI Agents

- `commandbook new` and `commandbook edit` are **interactive** — they prompt for input via stdin. If your environment does not support interactive stdin, use the Command Book GUI or construct the database entry directly.
- `commandbook run <slug>` without a slug launches an interactive picker. Always pass the slug explicitly.
- `commandbook run` is a **long-running foreground process**. It does not return until the command exits or is interrupted. Run it in a background shell or with a timeout if you need to continue other work.
- The CLI binary is at `~/.local/bin/commandbook`. If not in PATH, use the full path.
- If you get `command not found`, the user needs to install CLI tools from Command Book's Settings or File menu.