Shell Integration

Command Book runs commands exactly as your terminal would: Same PATH, same aliases, same environment. Your tools just work.

How Commands Run

Command Book executes commands through your login shell, preserving your full terminal environment.

Login Shell Detection

On launch, Command Book detects your configured login shell:

• zsh (macOS default since Catalina)
• bash
• fish
• Other POSIX-compatible shells

You can see your detected shell in Settings → General.

Execution Method

Commands run using the login shell with interactive flags:

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

The -l (login) flag ensures:

• Your shell profile is loaded (.zshrc, .bashrc, .bash_profile)
• PATH is fully configured
• Shell aliases are available
• Environment variables from your profile are set

Environment Inheritance

What's Inherited

Your commands have access to:

• PATH: All directories in your shell's PATH
• Aliases: Shell aliases defined in your profile
• Functions: Shell functions from your profile
• Environment variables: Variables exported in your profile
• Tool configurations: nvm, pyenv, rbenv, etc.

Per-Command Variables

Add environment variables specific to a command:

1. Edit the command (⌘E)
2. Add variables manually in the Environment Variables section, or import them from a .env file using the "Browse for .env file or drop here" button or drag-and-drop
3. Save the command

These are added on top of your shell environment.

When you set a working directory that contains .env files, Command Book auto-imports them for new commands. See the Command Configuration docs for details on supported .env formats and variant files.

Common Scenarios

Using nvm/Node.js

If you use nvm, your Node.js version is automatically available:

# This works if nvm is in your shell profile
node server.js
npm run dev

Using Python Virtual Environments

For Python projects, activate the venv in your command:

source venv/bin/activate && python app.py

Or set the working directory and use:

./venv/bin/python app.py

Using Docker

Docker commands work as expected:

docker-compose up
docker run -p 8080:80 nginx

Troubleshooting

Command Not Found

If a command works in Terminal but not in Command Book:

1. Check if the tool is in your PATH
2. Verify your shell profile exports the PATH correctly
3. Try using the full path to the command
4. Ensure your .zshrc or .bashrc exports PATH outside of any interactive shell checks

Debugging with Ad-hoc Commands: Use ad-hoc commands to debug PATH issues. Open the command palette and run:

• $PATH - Shows what Command Book sees as your PATH
• which <tool> - Checks if a tool is in your PATH

For example, running which brew:

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

Environment Variable Missing

If an expected variable is missing:

1. Ensure it's exported in your shell profile (not just set)
2. Add it as a per-command environment variable
3. Check that your shell profile doesn't have conditional logic that skips the export

Shell Profile Not Loading

Ensure your profile is a login shell profile:

• zsh: Use .zprofile or .zshrc
• bash: Use .bash_profile or .bashrc

External Terminal Integration

Command Book integrates directly with your preferred terminal emulator for tasks that need a full terminal environment.

Open in Terminal

Opens a new terminal window at a command's working directory. Right-click a command in the sidebar or use the Commands menu:

• "Open in Warp" -- one-click action using your preferred terminal
• "Open in ... ▸" -- submenu to pick a different terminal

Run in Terminal

Launches the command in an external terminal with the correct working directory and pre-command. This is the escape hatch for commands that need interactive input, a real TTY, or other terminal features that Command Book doesn't provide. You can keep these commands organized in Command Book while running them with full terminal flexibility.

• "Run in Warp" -- one-click action using your preferred terminal
• "Run in ..." submenu -- pick a different terminal for one-off runs

Supported Terminals

Command Book detects and supports 6 terminal emulators:

Set your preferred default in Settings → General → External Terminal. If the preferred terminal is uninstalled, Command Book falls back to Terminal.app.

Shell Settings

View shell information in Settings → General:

• Detected shell path
• Shell version
• Profile file location