Bob Command Mode

Bob Command Mode runs bob commands from Obsidian with safe-write guards and run history.

Plugin facts¶

Registered commands¶

Run commands¶

Every catalog entry whose positionals are all optional and whose policy is run also appears as a command palette command named Bob: <title> with id run-<entry-id> (for example Bob: Today's plan as run-plan). These ids are generated from the cached catalog at load, so the inventory scanner does not list them here. Each one runs its entry through the same run engine and finishes with an outcome toast. Bob: Rerun last command repeats the newest recorded command with its original arguments and preview setting. Bob: Show last output opens the output pager on the newest run.

Keyboard and Vim¶

With Vim mode enabled, : in normal mode opens the sheet. Escape closes it. In the list, ↑ / ↓ and Ctrl+P / Ctrl+N move between rows; Enter runs, Tab opens argument mode, Shift+Enter previews, Ctrl+Enter runs without preview, and ? after a query opens bob <command> --help. Typing :: opens Vim's ex line. Vim commands such as :%s/foo/bar/ and :42 are routed to Vim, and matching exmap commands can be selected from suggestions. The catalog also includes named Pomodoro session actions to start, stop, extend, and shorten a session. Free-text bob capture TEXT is not accepted in command mode; use the dedicated capture workflow for free-text capture.

In argument mode, Tab accepts the selected completion, arrows or Ctrl+P / Ctrl+N move through completions, and Enter accepts a completion. Shift+Enter previews and Ctrl+Enter runs the typed command; Escape returns to the list. A preview is applied with Ctrl+Enter. A writer without a preview requires Ctrl+Enter or the Run button on its confirmation card.

In the pager, j / k scroll a line and d / u scroll half a page; g / G go to the start or end. / starts search, n / N move between matches, and w toggles wrapping. y copies output, Y copies the shell-quoted command, r reruns, and [ / ] move through history. : returns to the list, Escape returns to the prior stage, and q closes the sheet.

Bind Vim's keys with non-recursive mappings so replaying : cannot reopen the sheet recursively:

exmap bob_command obcommand bob-command-mode:open
nnoremap : :bob_command<CR>
nnoremap g: :

Insert-mode : remains text, visual-mode : remains native, and g: opens Vim's native ex line even if the plugin is disabled. The plugin warns if a recursive map replays :. If : does nothing, run bob plugins sync on that host, confirm bob plugins list shows it enabled, then reload Obsidian.

Feedback¶

Finished runs use toast cards for completed, needs-attention, failed, unknown, and stopped outcomes. Cards show a short summary, elapsed time, and the command line; their actions can open a note or conflict log, scan queued intake, reload deployed plugins, retry, copy the command, or open the saved output. Failed and unknown cards remain until dismissed. The status-bar chip appears after a run has lasted 400 ms, shows active run counts and elapsed time, and turns amber when a writer passes its budget. Clicking it opens the active run's pager.

When a run takes more than 15 seconds and Obsidian is unfocused, the enabled OS notification opens that run's pager when clicked. The OS notifications setting controls this behavior.

Output pager¶

The output pager is a bottom sheet that streams a run's stdout and stderr, replays finished runs in arrival order, and doubles as run history. It renders ANSI color against theme variables, ticks stderr with a faint red gutter, pretty-prints a body that is a single JSON document, and turns vault paths and [[wikilinks]] that resolve into note links. Vim-style keys scroll, search, wrap, copy (ANSI-stripped output with y, the shell-quoted command with Y), rerun, stop, and step through history newest-first. Toast Output, the status chip, OS notification clicks, and api.commandMode.openOutput all open this view. A run whose pager is open and focused at finish updates the status pill and skips the toast.

Command sheet¶

Bob: Command mode opens a bottom sheet with a fuzzy finder over every catalog entry, ranked by path, alias, title, and keywords with frecency tie-breaks. An empty query shows RECENT runs, FOR THIS NOTE rows filled from the active note (ref, area, project, and article notes each get their own rows), FROM CLIPBOARD rows for an http(s) URL, and one section per catalog section plus surface rows that run existing Obsidian commands (daily note, themes manager, stats, tasks, relation labels, reading board, article formatting). Unavailable rows stay visible and dimmed with their reason. Enter runs, Tab names argument mode (it lands with the args-vim phase), Shift+Enter dry-runs a preview into the sheet, Ctrl+Enter runs now, and a trailing ? shows bob <path> --help for the selected row. Preview-first rows stream their preview in place and apply with Ctrl+Enter; writers without a dry run ask once on an amber confirm card that only Ctrl+Enter or Run confirms. Reports grow the sheet into the output pager in place, and Esc returns to the list with the query intact.

Run engine¶

Runs are detached, file-backed children: spawn(bobPath, argv) with output to per-run files under command-mode/runs/ in the host state directory, an exit receipt when the catalog advertises run-receipt, and a JSON run record per run. Writers run one at a time behind a save-every-open-note guard; reads run in parallel. Read budgets kill the child, writer budgets mark the run overdue, and stop is offered only for runs this instance spawned. A plugin reload adopts unfinished records from their receipts, or reports unknown when no receipt arrives in time.

Run records and stdout/stderr files live under ${XDG_STATE_HOME:-~/.local/state}/bob-cli/command-mode/runs/. They are host-local rather than vault data.

Settings¶

Automation API¶

Other plugins reach the engine through app.plugins.plugins["bob-command-mode"].api.commandMode (version 1): run(argv, opts) settles {ok, runId, outcome, exitCode, reason?} and never rejects, openOutput(runId) opens that run in the output pager, onRunFinished(cb) subscribes to finishes, and catalog() and lastRun() read the cached catalog and newest record. Every finish also fires bob-command-mode:run-finished on the workspace with {runId, argv, entryId, outcome, effect, invalidates}.