CLI Reference

Command-line tools for managing clhorde. The system uses three binaries: clhorded (daemon), clhorde (TUI), and clhorde-cli (CLI).

Daemon required

Most clhorde-cli commands require the clhorded daemon to be running. Start it with: clhorded &

Local config commands (qp, keys, config) work without the daemon.

`clhorde-cli submit`

Submit a prompt to the running daemon. Requires clhorded.

Synopsis

$ clhorde-cli submit "prompt text" [--mode interactive|one-shot] [--cwd path] [--worktree]

Options

`--mode <mode>`	Prompt mode: `interactive` (default) or `one-shot`
`--cwd <path>`	Working directory for the prompt
`--worktree`	Enable git worktree isolation

Examples

$ clhorde-cli submit "Review the auth module"
Submitted prompt #1

$ clhorde-cli submit "Fix login bug" --mode one-shot --worktree
Submitted prompt #2

$ clhorde-cli submit "Explain this code" --cwd /path/to/project
Submitted prompt #3

`clhorde-cli status`

Show daemon status and prompt summary. Requires clhorded.

$ clhorde-cli status
Workers: 2/3 active
Mode: interactive

ID   STATUS         MODE          PROMPT
----------------------------------------------------------------------
1    ✔ completed   interactive   Review the auth module...
2    ↻ running      interactive   Fix the login bug...

`clhorde-cli attach <id>`

Attach to a prompt and stream its output to stdout. Requires clhorded.

For completed/failed prompts, prints the full output and exits. For running prompts, streams live output until the worker finishes.

$ clhorde-cli attach 1
# Output streams to stdout...

`clhorde-cli store`

Manage persisted prompts. All store commands route through the daemon. Requires clhorded.

`store list`

List all stored prompts with their UUID, state, mode, and truncated prompt text.

$ clhorde-cli store list
UUID                                   STATE       MODE          PROMPT
----------------------------------------------------------------------
019462ab-...                           completed   interactive   Review auth code...
019462ac-...                           failed      one-shot      Fix login bug...

`store count`

Show prompt counts grouped by state.

$ clhorde-cli store count
completed: 12
failed: 3
pending: 2
total: 17

`store path`

Print the storage directory path.

$ clhorde-cli store path
/home/user/.local/share/clhorde/prompts

`store drop <filter>`

Delete stored prompts matching the filter.

$ clhorde-cli store drop all          # Drop everything
$ clhorde-cli store drop completed    # Drop completed only
$ clhorde-cli store drop failed       # Drop failed only
$ clhorde-cli store drop pending      # Drop pending only
$ clhorde-cli store drop running      # Drop running only

Valid filters: all, completed, failed, pending, running

`store keep <filter>`

Keep only prompts matching the filter, delete everything else.

$ clhorde-cli store keep completed    # Keep completed, drop rest
$ clhorde-cli store keep failed       # Keep failed, drop rest

Valid filters: completed, failed, pending, running

`store clean-worktrees`

Scan all persisted prompts for associated git worktree paths and remove them via git worktree remove. Clears the worktree_path from each prompt file.

$ clhorde-cli store clean-worktrees
  removed: /home/user/projects/myrepo-wt-3/
  skip (already gone): /home/user/projects/myrepo-wt-5/
Cleaned 1 worktree(s), 1 already gone, 0 error(s).

`clhorde-cli keys`

Manage keybindings without editing TOML by hand. Works without the daemon.

`keys list [mode]`

List all keybindings, or bindings for a specific mode.

$ clhorde-cli keys list              # All modes
$ clhorde-cli keys list normal       # Normal mode only

Output format matches TOML syntax so you can copy-paste into your config.

`keys set <mode> <action> <key1> [key2...]`

Set the keys for an action. Replaces any existing keys.

$ clhorde-cli keys set normal quit Q          # Remap quit to Q
$ clhorde-cli keys set view back Esc q        # Multiple keys

`keys reset <mode> [action]`

Reset bindings to defaults. Without an action, resets the entire mode.

$ clhorde-cli keys reset normal quit          # Reset one action
$ clhorde-cli keys reset normal               # Reset entire mode

Valid modes

normal, insert, view, interact, filter

Valid actions by mode

Mode	Actions
`normal`	`quit`, `insert`, `select_next`, `select_prev`, `view_output`, `interact`, `increase_workers`, `decrease_workers`, `toggle_mode`, `retry`, `resume`, `move_up`, `move_down`, `search`, `half_page_down`, `half_page_up`, `go_to_top`, `go_to_bottom`
`insert`	`cancel`, `submit`, `accept_suggestion`, `next_suggestion`, `prev_suggestion`
`view`	`back`, `scroll_down`, `scroll_up`, `interact`, `toggle_autoscroll`, `kill_worker`, `export`
`interact`	`back`, `send`
`filter`	`confirm`, `cancel`

`clhorde-cli qp`

Manage quick prompts—single-keypress messages for running workers. Works without the daemon.

`qp list`

List all configured quick prompts.

$ clhorde-cli qp list
c = "continue"
g = "let's go"
y = "yes"

`qp add <key> <message...>`

Add or update a quick prompt. The message is everything after the key.

$ clhorde-cli qp add g "let's go"
Added quick prompt: g = "let's go"

`qp remove <key>`

Remove a quick prompt.

$ clhorde-cli qp remove g
Removed quick prompt: g

`clhorde-cli config`

Manage the config file. Works without the daemon.

`config path`

Print the config file path.

$ clhorde-cli config path
/home/user/.config/clhorde/keymap.toml

`config init [--force]`

Create a config file with all default values populated. Use --force to overwrite an existing file.

$ clhorde-cli config init
Created config: /home/user/.config/clhorde/keymap.toml

$ clhorde-cli config init --force    # Overwrite existing

`config edit`

Open the config file in $EDITOR (falls back to vi). Creates the file with defaults if it doesn't exist.

$ clhorde-cli config edit

`clhorde prompt-from-files`

Read file contents and queue them as prompts, then launch the TUI. Each file becomes one pending prompt. All prompts automatically run with worktree isolation, so each gets its own git worktree.

Synopsis

$ clhorde prompt-from-files [--run-path <path>] <file1> [file2...] or <file1,file2,...>

Options

--run-path <path> Set the working directory (and git repo) for all prompts. Must be an existing directory.

Details

Shell glob expansion works (e.g., tasks/*.md)
Multiple file arguments are supported
Comma-separated paths within a single argument are split into individual files
Empty files are skipped with a warning
Unreadable files are skipped with a warning
If no valid prompts are loaded, the command exits with an error
Worktree isolation is always enabled — each prompt gets its own git worktree
Use --run-path to target a specific repository when running from a different directory

Examples

$ clhorde prompt-from-files tasks/*.md                          # Load all .md files as prompts
$ clhorde prompt-from-files --run-path /path/to/repo tasks/*.md # Run in a specific directory
$ clhorde prompt-from-files a.txt b.txt c.txt                   # Load specific files
$ clhorde prompt-from-files a.txt,b.txt c.txt                   # Comma + space separated