Running Ad-hoc Commands

Sometimes you need to run something once without cluttering your command library. Ad-hoc commands give you that flexibility.

Edition limits: The personal edition includes 10 ad-hoc commands in history. The full edition has unlimited ad-hoc command history.

What Are Ad-hoc Commands?

Ad-hoc commands let you run quick, one-off terminal commands without saving them to your command library. Perfect for:

• Quick tests or experiments
• One-time tasks
• Commands you don't need to repeat

Running an Ad-hoc Command

1. Press ⌘K to open the Command Palette
2. Type your command directly in the search field
3. Select Run Command to execute immediately

The command runs immediately and appears in the sidebar like any other process.

Example: Open the palette, type ls ., and select "Run Command".

Command History

Command Book remembers your ad-hoc command history:

• Recent commands appear in the ad-hoc dialog
• Click a previous command to reuse it
• History persists across app restarts

Ad-hoc Runs from the CLI

The CLI has its own ad-hoc path: pass --command instead of a slug and Command Book runs it without saving it.

# Run it in the foreground, attached to your terminal
commandbook run --command "python -m http.server 8000" --name file-server --dir .

# Or start it in the background and get your prompt back
commandbook start --command "npm run dev" --name web --dir .

The process is fully managed — commandbook status file-server, commandbook logs file-server, and commandbook stop file-server all work on it, addressed by the --name handle you gave it (or one derived from the command's first token if you omit --name). It just isn't added to your saved command list.

Two differences from an ad-hoc command you run in the app are worth knowing:

• A CLI ad-hoc run gets no sidebar row. The app adopts CLI runs of saved commands into their existing row, but a throwaway run has no row to adopt, and inventing a temporary one would churn a hand-ordered sidebar. Watch it with commandbook logs --follow instead.
• It leaves nothing behind. Once it exits, commandbook status on that slug returns 404. There's no ad-hoc history to browse the way the palette keeps one — though its captured output is still readable with commandbook logs until retention rolls it off.

This is the right tool for one-off automation and for AI agents, which shouldn't be adding throwaway entries to your command library. See the CLI documentation and the AI Agents guide.

Converting to Saved Commands

If you find yourself running the same ad-hoc command frequently, you can promote it to a full saved command:

1. Run the ad-hoc command
2. Right-click on the running process in the sidebar
3. Select Promote to Saved Command
4. Edit the name, working directory, and settings as needed
5. Click Save

This lets you add a proper name, working directory, environment variables, and auto-restart settings.

Differences from Saved Commands

Use Cases

Quick file operations:

tail -f /var/log/system.log

Testing a new tool:

npx create-react-app test-project

Debugging PATH issues:

echo $PATH
which brew

Tip: Command Book excels at streaming output -- logs, servers, builds, and watchers. For commands that need interactive input or a real TTY, save them as a full command and use "Run in Terminal" to launch them in your preferred terminal emulator while keeping them organized in Command Book.