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:
- Keyboard shortcut: Press ⌘N from the main window
- Menu: File > New Command...
- Command Palette: Press ⌘K to open the command palette, then click "Create New Command" at the bottom
- 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:
- In the command palette, select the command, press ⌘E or right-click and choose Edit
- Or if the command is in the sidebar (recently run), select it and press ⌘E or right-click and choose Edit
- Make your changes
- 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
.envfiles) - 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
- Edit a command (⌘E or right-click → Edit)
- In the Environment Variables section, enter a key and value
- Click the + button to add it
- Save the command
Common uses:
NODE_ENV=developmentfor Node.js appsFLASK_DEBUG=1for Flask debuggingDATABASE_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
.envfile - Drag and drop: Drag a
.envfile 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:
.env-- base variables.env.local-- local overrides (typically gitignored).env.development-- development-specific settings.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=VALUEpairs (one per line)- Comments starting with
# - Blank lines (ignored)
- Quoted values (single or double quotes)
exportprefix (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 -i -c flags:
/bin/zsh -l -i -c "your command here"
This ensures:
- Your PATH is properly set
- Shell aliases are available
- Environment from
.zshrc/.bashrcis 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:
- Sidebar: Right-click a saved command and select Choose Icon
- 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
Command Book detects 8 terminal emulators automatically: macOS Terminal, iTerm2, Warp, Ghostty, Kitty, Alacritty, Rio, and cmux. Set your preferred default in Settings → General → External Terminal.
Using a Terminal That Isn't Listed
If your terminal isn't one of those, click Choose Other App… in Settings → General → External Terminal and pick it. It then appears in the "Open in" and "Run in" menus and can be your default.
For most terminals there's nothing else to set up. Command Book hands the app the working directory for "Open in". For "Run in", terminals that open shell scripts (cmux, for example) get a script that loads your login shell environment, runs the command, and leaves a shell open when it ends.
If your terminal needs specific flags, fill in the optional Open arguments and Run arguments fields. They take three placeholders:
| Placeholder | Replaced with |
|---|---|
{dir} |
The command's working directory |
{script} |
A script that runs the command (with its pre-command) |
{shell} |
Your login shell |
For example, --working-dir {dir} -e {script} as the run arguments. When arguments are set, Command Book starts a new instance of the app, because most terminals ignore arguments sent to a copy that's already running. Use Change… or Remove to swap or drop the custom 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.
Microphone and Camera Access
Commands that record audio or video, such as speech-to-text CLIs, ffmpeg, sox, or OpenCV scripts, work in Command Book just as they do in Terminal. macOS treats anything Command Book launches as Command Book asking, so the first time a command needs the microphone or camera you'll see the standard macOS permission prompt for Command Book. Allow it once and it works from then on.
If you denied the prompt earlier, turn access back on in System Settings → Privacy & Security → Microphone (or Camera).
Tips
- Use full paths for commands when possible for reliability
- Test commands in Terminal first before saving
- Set working directories to avoid path issues
- Use environment variables instead of hardcoding values
- Use "Run in Terminal" for commands that need interactive input or full TTY features