Configuring Commands

Your saved commands are the heart of Command Book -- the processes you run repeatedly that deserve a permanent home. Here's how to configure them.

Creating Commands

There are several ways to create a new command:

  1. Keyboard shortcut: Press ⌘N from the main window
  2. Menu: File > New Command...
  3. Command Palette: Press ⌘K to open the command palette, then click "Create New Command" at the bottom
  4. Promote ad-hoc: Run an ad-hoc command from the command palette, then right-click it in the sidebar and select "Promote to Saved Command"

Editing Commands

To edit an existing command:

  1. In the command palette, select the command, press ⌘E or right-click and choose Edit
  2. Or if the command is in the sidebar (recently run), select it and press ⌘E or right-click and choose Edit
  3. Make your changes
  4. Click Save

If the command is currently running, changes apply the next time you start it.

Duplicating Commands

Right-click a command in the palette and choose Duplicate. This creates a copy you can modify independently -- useful when you need similar commands with slight variations.

Deleting Commands

In the command palette, select the command and press ⌘⌫, or right-click and choose Delete. You can also delete commands from the sidebar.

Command Properties

Each saved command has the following properties:

Basic Settings

  • Name: Display name shown in the sidebar and command palette
  • Command: The shell command to execute
  • Working Directory: The directory to run the command from
  • Icon: Auto-detected from the command text, or manually chosen from 60+ technology icons

Advanced Settings

  • Environment Variables: Custom environment variables for this command (can be imported from .env files)
  • Auto-Restart: Automatically restart if the process crashes (only triggers on non-zero exit codes)
  • Restart Delay: Wait time before auto-restart (1-60 seconds). A countdown is shown in the sidebar.

Environment Variables

You can set custom environment variables for each command. These are added to your shell's existing environment.

Adding Variables Manually

  1. Edit a command (⌘E or right-click → Edit)
  2. In the Environment Variables section, enter a key and value
  3. Click the + button to add it
  4. Save the command

Common uses:

  • NODE_ENV=development for Node.js apps
  • FLASK_DEBUG=1 for Flask debugging
  • DATABASE_URL=postgres://... for database connections

Importing from .env Files

Instead of entering variables one at a time, you can import them from a .env file:

  • Browse: Click the "Browse for .env file or drop here" button in the Environment Variables section and select your .env file
  • Drag and drop: Drag a .env file directly onto the Environment Variables section

Imported variables are merged with any existing variables. If a variable already exists, the imported value takes precedence.

Auto-Import from Working Directory

When creating a new command, Command Book automatically checks the working directory for .env files. If any are found and the command has no environment variables set yet, they are imported automatically.

The following files are checked in order, with later files overriding earlier ones:

  1. .env -- base variables
  2. .env.local -- local overrides (typically gitignored)
  3. .env.development -- development-specific settings
  4. .env.production -- production-specific settings

Auto-import only happens once per editing session. If you clear the variables and change the working directory, it won't re-import.

.env File Format

Command Book supports the standard .env format:

# Database configuration
DATABASE_URL=postgres://localhost/mydb
DB_PORT=5432

# API settings
API_KEY="my secret key"
NODE_ENV=development

export FLASK_DEBUG=1

Supported syntax:

  • KEY=VALUE pairs (one per line)
  • Comments starting with #
  • Blank lines (ignored)
  • Quoted values (single or double quotes)
  • export prefix (stripped automatically)
  • Inline comments with # (space before hash, unquoted values only)
  • Values containing = (split on first = only)

Note: Command Book automatically sets FORCE_COLOR=1, CLICOLOR_FORCE=1, and COLORTERM=truecolor to encourage color output in commands.

Auto-Restart

When enabled, Command Book will automatically restart a command if it exits unexpectedly.

  • Crash detection: Only restarts on non-zero exit codes (exit code 0 = normal exit, no restart)
  • Countdown display: Shows restart countdown in the sidebar
  • Configurable delay: Set between 1-60 seconds
  • Cancel anytime: You can cancel a pending restart

This is especially useful for development web servers that auto-reload on file changes. If the code has a syntax error at reload time, the server crashes. Command Book notices and restarts it automatically, retrying until it succeeds.

Shell Integration

Commands run through your login shell (bash, zsh, fish, etc.) with the -l -c flags:

/bin/zsh -l -c "your command here"

This ensures:

  • Your PATH is properly set
  • Shell aliases are available
  • Environment from .zshrc/.bashrc is loaded

Custom Icons

Command Book auto-detects icons based on your command text -- Python, Node, Docker, and 60+ other technologies are recognized automatically.

To override the auto-detected icon:

  1. Sidebar: Right-click a saved command and select Choose Icon
  2. Command Editor: Use the icon picker when creating or editing a command

Icons are organized by category: Languages, Package Managers, Web Frameworks, Databases, DevOps & Cloud, and Tools & Other. Select Auto-Detect to reset back to automatic detection.

Custom icons are only available for saved commands (not ad-hoc commands).

Open in Terminal

Open a new terminal window at a command's working directory. Useful when you need to run quick commands or investigate something in the same directory as a running process.

  • Quick action: Right-click a command in the sidebar or use the Commands menu → "Open in [Your Default Terminal]"
  • Pick a terminal: Use the "Open in Terminal ▸" submenu to choose from all detected terminals

Supports 6 terminal emulators: Terminal.app, iTerm2, Warp, Ghostty, Kitty, and Alacritty. Set your preferred default in Settings → General → External Terminal.

Run in Terminal

Run in Terminal is the escape hatch for commands that don't run correctly inside Command Book. Some commands need a real TTY, require interactive input, or depend on terminal features that Command Book doesn't provide. Rather than leaving these commands unmanaged, "Run in Terminal" lets you define and organize them in Command Book while running them with the full flexibility of an external terminal.

  • Quick action: Right-click a command → "Run in [Your Default Terminal]"
  • Pick a terminal: Use the "Run in ..." submenu for one-off choices

The command launches in the external terminal with the correct working directory and pre-command, exactly as it would run inside Command Book. This means Command Book can serve as the single source of truth for all your commands, even ones that need a full terminal to execute properly.

Tips

  1. Use full paths for commands when possible for reliability
  2. Test commands in Terminal first before saving
  3. Set working directories to avoid path issues
  4. Use environment variables instead of hardcoding values
  5. Use "Run in Terminal" for commands that need interactive input or full TTY features