Frequently Asked Questions

Command Book is a native macOS application for managing long-running terminal commands. Instead of juggling fragile terminal tabs that can be lost or closed, Command Book provides a dedicated, persistent interface that saves commands, runs them reliably, captures output, and remembers everything across app restarts.

Terminal tabs weren't designed for long-running processes. They're fragile, forgetful, and demand constant attention. Command Book gives your background processes a permanent home:

• Persistent -- Commands survive app restarts; never rebuild your setup again
• Purpose-built -- Designed specifically for servers, workers, and services you leave running
• Native -- Built with SwiftUI and Swift 6, not Electron; minimal resource usage
• Keyboard-first -- ⌘K command palette, full keyboard navigation, signal shortcuts

Yes! Command Book includes a full command-line interface. Run, list, create, and edit saved commands directly from your terminal:

commandbook run api-server      # Run a saved command
commandbook list                 # List all commands
commandbook new                  # Create a new command
commandbook edit api-server      # Edit an existing command
commandbook open                 # Open the GUI app

Install it from Settings → CLI Tools or File → Install CLI Tools in the app. The CLI and GUI share the same database, so commands created in one are immediately available in the other.

See the CLI documentation for the full reference.

You can, but you'd be maintaining two systems. Shell aliases require you to manually replicate command names, working directories, environment variables, and pre-commands in your shell configuration files. Every time you update a command in Command Book, you'd need to update the alias too.

The CLI eliminates that. It reads directly from the same SQLite database as the GUI, so your commands are defined once and available everywhere -- a single source of truth. Edit a command in the app, and commandbook run picks up the change immediately. No syncing, no drift between your shell files and your saved commands.

This also makes the CLI a natural fit for automation. Scripts, CI pipelines, and AI coding agents can invoke your saved commands by name without needing to know the underlying details.

Terminal emulators are general-purpose tools for interactive shell sessions. Command Book is purpose-built for long-running background processes -- the servers, workers, and services you start and leave running. It's not a replacement for your terminal; it's a companion for the complex commands you need to monitor and manage over time.

In fact, Command Book integrates with your terminal. "Open in Terminal" jumps to a command's working directory in your preferred terminal, and "Run in Terminal" launches a command directly in it. Command Book supports Terminal.app, iTerm2, Warp, Ghostty, Kitty, and Alacritty -- set your preferred default in Settings.

No. Command Book runs commands through your login shell and captures their output, but it's not a full terminal emulator. It doesn't support interactive prompts, TTY/PTY features, or programs that require cursor control (like vim or htop). It's designed for non-interactive processes that produce streaming output. Think npm run dev or python app.py --reload type of commands.

That said, Command Book's "Run in Terminal" feature is the escape hatch for commands that need a real terminal. You can still organize and manage those commands in Command Book, then launch them in your preferred terminal emulator (Terminal.app, iTerm2, Warp, Ghostty, Kitty, or Alacritty) with one click.

Yes. Command Book detects your login shell and runs commands using your shell's -l -c flags. This means your .zshrc, .bashrc, or fish config files are sourced, giving you access to your PATH, aliases, and environment variables just as if you ran them in your terminal of choice.

Command Book doesn't support interactive stdin directly. Commands that require user input (password prompts, confirmation dialogs, interactive REPLs) won't work as expected inside Command Book. It's designed for processes that run autonomously after starting. Often, command-line flags can serve the same purpose as user input (e.g. apt install -y wget to avoid confirmations).

For commands that truly need interactivity, use "Run in Terminal" -- right-click the command in the sidebar and select "Run in [Your Terminal]". This launches the command in a full terminal emulator with all TTY features, while still letting you organize and manage the command from within Command Book.

Command Book is designed for developers, data scientists, and devops folks who:

• Run multiple local services during development (web servers, databases, workers)
• Need to monitor long-running processes (ML training, data pipelines, builds)
• Value keyboard efficiency over mouse input
• Want their process setup to survive terminal crashes and restarts
• Appreciate efficient, native macOS apps over resource-intensive Electron apps

Command Book is currently macOS only, requiring macOS 15.0 (Sequoia) or later. A Windows version is planned -- stay tuned for updates. There are no current plans for a Linux version, but we're always listening to feedback.

Command Book stops each process cleanly. If you have running processes, Command Book shows a confirmation dialog listing them (configurable). If you choose to quit, all processes receive SIGTERM with a 10-second timeout, then SIGKILL if they haven't terminated. This means well-behaved processes will shut down gracefully with the opportunity to close database connections, flush open files, and more.

Yes. You can close the window and Command Book continues running in the Dock. Your processes keep running and output keeps capturing. Click the Dock icon to bring the window back.

• Stop sends SIGTERM, giving the process a chance to shut down gracefully
• Force Stop sends SIGKILL, which terminates the process immediately without cleanup

Most of the time, use Stop. Use Force Stop only when a process is unresponsive. Using Stop gives each process the opportunity to close database connections, flush open files, and more.

Restart sends SIGTERM to stop the process, waits for it to gracefully terminate, then starts it again with the same command and configuration. It's equivalent to Stop followed by Start.

Enable "Restart on crash" when creating or editing a command. Set a delay (1-60 seconds). If the process exits with a non-zero code, Command Book waits the specified delay (showing a countdown), then restarts automatically. You can cancel the pending restart anytime.

This is especially useful for development-level web servers. Many of these servers auto-detect changes to source files and restart automatically. Most of the time, this is fairly transparent. But if the code change results in an invalid state at the very moment it tries to restart (think unmatched { as you type), the load fails and the process ends entirely. You have to notice this and restart it using terminal. With Command Book, it will notice for you and restart a few moments later, retrying until it succeeds.

No. Auto-restart only triggers when a process exits with a non-zero exit code (indicating an error or crash). If a process exits cleanly with code 0, it stays stopped.

Command Book supports the full signal hierarchy:

• SIGINT -- Graceful interrupt (Ctrl+C equivalent)
• SIGHUP -- Close stdin (Ctrl+D equivalent)
• SIGTERM -- Standard termination request
• SIGKILL -- Force kill immediately

Press ⌘K to open the command palette, then click "Create New Command" at the bottom. Enter a name, working directory, and the command text. Click Save.

Other ways to create new commands include:

• Press ⌘N from the main window
• Running an ad-hoc command from the command palette ⌘K, then promote it to a full, saved command from the sidebar (right click)

Yes. In the command palette, select the command, right-click and choose Edit. Make changes and save. If the command is currently running, changes apply the next time you start it.

If the command is saved in the sidebar (recently run, not closed), then you can also right-click and edit from the sidebar too.

Yes. Right-click a command in the palette and choose Duplicate. This creates a copy you can modify independently.

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

An ad-hoc command is one you run without saving. Open the palette, type a command, and select "Run Command" to execute it immediately. The command appears in your history for easy re-running but isn't saved as a permanent command.

An example of an ad-hoc command is tail -f /var/log/system.log. You can enter this directly in the command palette, hit run, and it'll run and be managed like a saved command. However, you can't set extra information like name, working directory, or environment variables unless you save it as a full command.

Yes. When editing a command, use the Environment Variables section to add variables manually, or import them from a .env file. You can browse for a .env file using the "Browse for .env file or drop here" button, or drag and drop one directly onto the section. These are set in addition to your shell's environment which are included for all commands.

Yes. Command Book has full .env file support:

• Import: Click "Browse for .env file or drop here" in the Command Editor or drag and drop a .env file onto the Environment Variables section
• Auto-import: When creating a new command, if the working directory contains .env files and no variables are set, they're imported automatically

Command Book checks for .env, .env.local, .env.development, and .env.production in order, with later files overriding earlier ones. The standard .env format is supported: KEY=VALUE pairs, comments, blank lines, quoted values, and the export prefix.

Pre-commands are shell commands that run before your main command each time it starts. For example, you might add git pull as a pre-command to always run the latest code before starting your web server.

Pre-commands run in the same working directory as the main command and share its environment. If a pre-command fails (non-zero exit code), the main command still runs.

"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 support. Rather than forcing you to leave Command Book entirely, "Run in Terminal" lets you keep those commands organized in Command Book while running them with the full flexibility of your preferred terminal emulator.

Right-click a command in the sidebar or use the Commands menu to find:

• "Run in [iTerm2]" -- one-click action using your preferred terminal (the label updates to show your default)
• "Run in Terminal ▸" -- a submenu listing all detected terminal apps for one-off choices

The command is launched in the external terminal with the correct working directory and pre-command, exactly as it would run inside Command Book. This means you can define and organize all your commands in one place, even if some of them need the flexibility of a full terminal to run properly.

"Open in Terminal" opens a new terminal window at the command's working directory. This is useful when you need to run quick commands or debug something in the same directory as a running process, without disrupting it.

It's available in the sidebar context menu and the Commands menu, with the same two-tier pattern:

• "Open in [iTerm2]" -- one-click open using your preferred terminal
• "Open in Terminal ▸" -- submenu to pick a different terminal

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

Yes. Command Book auto-detects icons based on your command text (Python, Node, Docker, etc.), but you can override the icon for any saved command.

• Sidebar: Right-click a saved command and select "Choose Icon" to pick from 60+ technology icons organized by category (Languages, Package Managers, Web Frameworks, Databases, DevOps & Cloud, Tools & Other)
• Command Editor: When creating or editing a command, use the icon picker in the editor form

Select "Auto-Detect" at any time to reset the icon back to automatic detection based on the command text.

Yes. Commands run through your login shell (-l flag), so they inherit your PATH, aliases, and any variables exported in your shell configuration files.

The free edition captures 25,000 lines per process. The full edition supports up to 500,000 lines, configurable in Settings → General (10K, 50K, 100K, or 500K). Larger buffers use more memory.

Command output is not stored across restarts of the Command Book app. However, output is preserved across multiple runs of the same command within a single session.

Yes! Command Book has rich search capabilities. Press ⌘F to open the search bar for the selected command's output. Features include:

• Case-sensitive or case-insensitive matching
• Regular expression support for advanced pattern matching
• Navigate between matches with ⌘G (next) and ⌘⇧G (previous)
• Match count display showing current position

Note: Search is per command, not across all commands simultaneously.

Some command-line tools disable colors when they detect they're not running in a real terminal. Command Book sets FORCE_COLOR=1, CLICOLOR_FORCE=1, and COLORTERM=truecolor to encourage color output, but not all tools respect these. Check your tool's documentation for forcing color output.

Yes. When viewing a process, right-click in the output area and select Clear. This clears the visible buffer but doesn't affect the running process.

Select text with your mouse, then ⌘C. Or right-click and choose Copy. To copy all output, right-click and select Copy All.

Command Book automatically detects URLs in output (http://, https://, file://). Click them to open in your default browser. Hover shows a pointing hand cursor.

Detected URLs are also collected at the top of each command window (up to 5 most recent), so you can easily access them even after the output containing the URLs has scrolled past.

Command Book supports full ANSI color output:

• Standard 8 colors
• Bright 8 colors
• 256-color palette
• 24-bit true color (16 million colors)
• Text styling: bold, dim, italic, underline, strikethrough

By default, commands are stored in ~/Library/Application Support/CommandBook/commandbook.sqlite. You can see the exact path in Settings → Storage.

Yes. In Settings → Storage, you can export your database to a file and import it on another machine or as a backup. The export creates a timestamped SQLite file you can store anywhere.

Settings → Storage → Export Database creates a timestamped backup file. Choose a destination and save. The export includes all saved commands and ad-hoc history.

Settings → Storage → Import Database. Select your backup file. Commands are merged with your existing commands. Database migrations run automatically if importing from an older version.

Not currently. You can manually export your database on one Mac and import it on another, but automatic sync is not yet supported. We're open to adding this feature in a future update.

Drag and drop. Grab a process and move it to your preferred position. The order is saved automatically.

Visual dividers you can add between process groups. Right-click in the sidebar to add a separator. Drag to reposition. Right-click to rename or delete.

Not with formal groups (yet), but you can use separators to visually organize processes. Name separators like "Frontend," "Backend," "Databases" to create sections.

It's a summary: number of running processes and their combined memory usage. This helps you see overall resource consumption at a glance.

Each command/process has memory usage shown at the bottom of the command window. Select a particular command to see its memory usage.

Hover over a process to see quick action buttons: Start/Stop, Restart, Dismiss. These let you control processes without right-click menus or other action buttons.

Yes. The sidebar is focused by default. Use arrow keys to navigate, Enter to start/stop processes, ⌘K to open the palette.

macOS 15.0 (Sequoia) or later.

Yes. Command Book is a universal binary supporting both Apple Silicon and Intel Macs.

No. Sandboxing is disabled because Command Book needs to spawn arbitrary processes and access any working directory. This is necessary for its core functionality. This is also why the app is not available on the Mac App Store.

It is notarized and signed by our developer certificate which allows it to run without Gatekeeper warnings on macOS.

No. Command Book is a native macOS app built with SwiftUI and Swift 6. No web technologies, no Chromium, minimal resource usage.

At the time of writing, Command Book uses 21 MB on disk and only 73 MB of memory when running. Compare that to your typical Electron cross-platform app which uses 500 MB of disk space and 300 MB of RAM.

The app itself uses minimal memory (typically 70-73 MB). Output buffers are the main memory consumers. With multiple active processes, expect ~100-300 MB total depending on your buffer size settings (free edition: 10K lines, full edition: up to 500K lines).

Yes! Command Book ships with a full CLI. Install it from Settings → CLI Tools or File → Install CLI Tools, then use commandbook run, commandbook list, commandbook new, and more directly from your terminal. The CLI and GUI share the same database. See the CLI documentation for details.

Ensure the tool is in your PATH and that your shell config exports it. Command Book runs commands with your login shell (-l -c), so if which <tool> works in Terminal, it should work in Command Book.

If not, check that your .zshrc or .bashrc exports the PATH correctly (not inside an interactive shell check).

Interestingly, Command Book's ad-hoc commands can help you debug errors. Just open the command palette, and type $PATH to output what Command Book sees as your PATH. Similarly, you can type which <tool> to see if it's in your PATH. For example, we get the output below for which brew

▶ Starting ad-hoc command: which brew
Directory: /Users/jane-user
Shell: zsh
─────────────────────────────────────
/opt/homebrew/bin/brew
─────────────────────────────────────
✓ Process exited cleanly (exit code 0)
Execution time: 0:00

Common causes:

• The command requires user input (not supported directly)
• The command checks for a real TTY and behaves differently
• Environment variables aren't being set correctly

See My command can't find a tool (command not found) just above for more information.

Tip: If the command genuinely needs a real terminal, use "Run in Terminal" from the sidebar context menu or Commands menu. This lets you keep the command saved and organized in Command Book while running it in your preferred terminal emulator with full TTY support. It's the best of both worlds -- Command Book as your command manager, your terminal for execution.

Some programs output control sequences for cursor positioning (clearing screen, moving cursor). Command Book doesn't support these. The output may show escape sequences literally. This is expected for TUI applications like htop, vim, or less.

If the process just started, the first memory reading may not have occurred yet (updates every 2 seconds). If it persists, the process may have already exited.

"Crashed" means the process exited with a non-zero exit code. Many programs use non-zero codes for expected conditions. The status shows the actual exit code (e.g., "Exit code: 130" for SIGINT). This is informational, not necessarily an error.

Such commands/processes will not work correctly for auto-restart as auto-restart will trigger if the exit code is non-zero.

Just email us at hello@commandbookapp.com. Include your macOS version, Command Book version (from the About window), and steps to reproduce the issue.

Command Book has a free edition that includes 5 saved commands, 10 ad-hoc commands, and 25,000 lines of output capture per process. The free edition is yours forever with no time limits.

After you've been using Command Book for awhile and you've found it valuable, consider upgrading to the full version for unlimited saved commands, unlimited ad-hoc commands, up to 500,000 lines of output capture, and sidebar separators to organize your commands. Not only do you get more value out of Command Book, but you're helping us continue to develop and improve the app.

The full edition is a one-time purchase of $14.99 USD. This unlocks unlimited saved commands, unlimited ad-hoc commands, up to 500,000 lines of output capture, and sidebar separators. Includes free updates within the same major version. No subscription, no account required.

Buy the full version at commandbookapp.com/buy.

No. Command Book is a one-time purchase. You pay once and own it forever. All updates within the same major version are included (e.g., if you purchase v1.x, you get all 1.x updates free).

No. Command Book doesn't require an account. Your license is tied to your email at the time of purchase, not an online account. In fact, you cannot create an account or login to Command Book at all.

The free edition is genuinely useful -- it's not a crippled demo. Five saved commands and 25,000 lines of output handle casual use just fine.

The paid edition is for developers who've made Command Book part of their daily workflow. Here's what you're actually buying:

• Unlimited saved commands -- No more choosing which processes matter most. Save your entire development stack: frontend, backend, databases, workers, log tails, whatever you need.
• 500K lines of output -- When a crash happens after hours of work, you want the full picture. Larger buffers mean you can scroll back further to find what went wrong.
• Command grouping -- Organize processes into logical groups. Small feature, real clarity when you're running 5+ services.
• Continued development -- Your purchase directly funds bug fixes, new features, and macOS compatibility updates. No VC runway, no enterprise upsell, no tracking, zero ensh*tification -- just a tool that keeps getting better because users support it.

At $14.99, that's less than 15 minutes of developer time. If Command Book saves you from rebuilding your terminal setup even once, it's paid for itself. Ready to make Command Book part of your daily workflow? Buy Command Book today.