bob themes¶

List, hide, unhide, color, and rename Pomodoro themes

Bare `bob themes` runs the read-only list. hide, unhide, color, and rename append to the vault journal.

Usage: bob themes [COMMAND]

Commands:
  color   Pin or unpin a theme's hue
  hide    Hide themes from Recent suggestion rows
  list    List remembered Pomodoro themes (default)
  rename  Rename a Pomodoro theme everywhere in one commit
  unhide  Show hidden themes in Recent suggestion rows again

Options:
  -h, --help  Print help

Bare `bob themes` runs the read-only list.

Examples:
  bob themes                   Visible themes from the last 90 days
  bob themes -q fix -f json    Rank FIX before FIXES as JSON
  bob themes hide BOOKS        Hide BOOKS from Recent rows
  bob themes unhide BOOKS      Put BOOKS back in Recent rows
  bob themes color BLOG red    Pin BLOG to red
  bob themes color BLOG auto   Drop the BLOG pin
  bob themes rename FIXES FIX -d   Preview a global rename

See docs/pomodoro-themes.md for identity, cache, hue, journal, and JSON.
Run 'bob themes <command> --help' for more information on a command.

Pin a Pomodoro theme to a palette slot, or pass auto to drop the pin so the hue rule (exempt, area, then name hash) applies again.

The write appends one theme.color event to .bob/themes/<host>.jsonl under bob_sync.lock (wait at most 3s). A pin that already matches is a no-op.

Usage: bob themes color [OPTIONS] <NAME> <HUE>

Arguments:
  <NAME>
          Theme name as it appears in a Pomodoro tail

  <HUE>
          Palette slot to pin, or auto to unpin

Options:
  -b, --bob-dir <DIR>
          Bob vault root; defaults to BOB_DIR or ~/bob

  -f, --format <FORMAT>
          Output format: human or json

          [default: human]
          [possible values: human, json]

  -h, --help
          Show help

Examples:
  bob themes color BLOG red
  bob themes color BLOG auto
  bob themes color BLOG red -f json

Slots: blue, orange, aqua, yellow, magenta, green, violet, red.

Environment:
  BOB_CONFIG_FILE         Exact Bob config file; defaults to ~/.config/bob/config.yml
  BOB_DIR                   Bob vault root when --bob-dir is omitted
  BOB_NOW                   Local datetime override that pins the event timestamp
  HOSTNAME                  Host label for the journal file; same slug vault-sync uses
  BOB_VAULT_SYNC_LOCK_FILE  Maintenance lock; defaults to ${XDG_RUNTIME_DIR:-/tmp}/bob_sync.lock

Exit codes:
  0  wrote the color event
  1  unknown theme, invalid hue, unchanged, lock busy, or I/O failure
  2  usage error

See docs/pomodoro-themes.md for the hue rule and the journal contract.

Hide one or more Pomodoro themes from Recent suggestion rows only. Today's ledger, typing the name, history, Stats, and colors stay unchanged. Using a hidden name never unhides it.

Each hide appends one theme.hide event to .bob/themes/<host>.jsonl under bob_sync.lock (wait at most 3s). A theme that is already hidden is a no-op.

Usage: bob themes hide [OPTIONS] <NAME>...

Arguments:
  <NAME>...
          Theme name as it appears in a Pomodoro tail

Options:
  -b, --bob-dir <DIR>
          Bob vault root; defaults to BOB_DIR or ~/bob

  -f, --format <FORMAT>
          Output format: human or json

          [default: human]
          [possible values: human, json]

  -h, --help
          Show help

Examples:
  bob themes hide BOOKS
  bob themes hide FIXES BOOKS -f json
  bob themes hide BOOKS --via bob-mac-capture -f json

Environment:
  BOB_CONFIG_FILE         Exact Bob config file; defaults to ~/.config/bob/config.yml
  BOB_DIR                   Bob vault root when --bob-dir is omitted
  BOB_NOW                   Local datetime override that pins the event timestamp
  HOSTNAME                  Host label for the journal file; same slug vault-sync uses
  BOB_VAULT_SYNC_LOCK_FILE  Maintenance lock; defaults to ${XDG_RUNTIME_DIR:-/tmp}/bob_sync.lock

Exit codes:
  0  wrote the hide event
  1  unknown theme, unchanged, lock busy, or I/O failure
  2  usage error

See docs/pomodoro-themes.md for hide semantics and the journal contract.

List Pomodoro themes derived from canonical daily notes.

A theme is one + component of a Pomodoro name. The catalog is read-only: it never writes the vault. Bare `bob themes` runs this command.

By default the list shows visible themes used in the last 90 days or today, newest first. Hidden themes stay out of the default list; they still exist in history, Stats, and colors. Use --all to include every known theme, --hidden to show only hidden themes, --query to rank exact/prefix matches before substring matches, and --fresh to ignore the machine-local cache.

Usage: bob themes list [OPTIONS]

Options:
  -a, --all
          List every known theme, flagging hidden ones

  -b, --bob-dir <DIR>
          Bob vault root; defaults to BOB_DIR or ~/bob

  -f, --format <FORMAT>
          Output format: human or json

          [default: human]
          [possible values: human, json]

  -F, --fresh
          Rebuild the catalog from daily notes, ignoring the cache

  -h, --help
          Show help

  -H, --hidden
          List only hidden themes

  -n, --limit <N>
          Show at most N themes after filtering and ranking

  -q, --query <Q>
          Rank exact and prefix matches first, then substring matches

Examples:
  bob themes
  bob themes list
  bob themes -q fix -f json
  bob themes -a -F
  bob themes -H
  bob themes -n 10 -q bo

Environment:
  BOB_CONFIG_FILE         Exact Bob config file; defaults to ~/.config/bob/config.yml
  BOB_DIR                   Bob vault root when --bob-dir is omitted
  BOB_NOW                   Local datetime override that pins today
  NO_COLOR                  Disable colored output
  XDG_CACHE_HOME            Cache root; catalog lives in <cache>/bob-cli/themes/

Exit codes:
  0  list
  1  vault I/O failure
  2  usage or config error

See docs/pomodoro-themes.md for identity, cache, hue, JSON, and journal writers.

Rename one Pomodoro theme across every canonical daily note (past, today, and future, open and closed) plus _templates/daily.md, in a single verified Git commit.

Only the theme component in ` — NAME` tails changes: separators keep their `+` spelling, a resulting duplicate collapses (`FIX + FIXES` → `FIX`), and every other byte is preserved. Prose, task text, and fenced examples are never touched.

The preview always rescans from source. The write takes bob_sync.lock, pre-syncs unless --offline, snapshots each target and compares again right before writing, writes atomically, appends one theme.rename journal event, verifies by rescanning, makes one commit, then post-syncs. Undo is `git revert`.

Usage: bob themes rename [OPTIONS] <OLD> <NEW>

Arguments:
  <OLD>
          Current theme name as it appears in a Pomodoro tail

  <NEW>
          New single theme name (must not contain +)

Options:
  -b, --bob-dir <DIR>
          Bob vault root; defaults to BOB_DIR or ~/bob

  -d, --dry-run
          Preview the rename without writing, committing, or syncing

  -f, --format <FORMAT>
          Output format: human or json

          [default: human]
          [possible values: human, json]

  -h, --help
          Show help

  -m, --merge
          Merge OLD into NEW when NEW is already used

  -o, --offline
          Commit locally; skip vault sync before and after

Examples:
  bob themes rename FIXES FIX -d
  bob themes rename FIXES FIX -d -f json
  bob themes rename OLD NEW --merge
  bob themes rename FIXES FIX -o

Environment:
  BOB_CONFIG_FILE         Exact Bob config file; defaults to ~/.config/bob/config.yml
  BOB_DIR                   Bob vault root when --bob-dir is omitted
  BOB_NOW                   Local datetime override that pins the event timestamp
  HOSTNAME                  Host label for the journal file; same slug vault-sync uses
  BOB_VAULT_SYNC_LOCK_FILE  Maintenance lock; defaults to ${XDG_RUNTIME_DIR:-/tmp}/bob_sync.lock

Exit codes:
  0  renamed (or dry-run planned)
  1  unknown theme, invalid name, unchanged, theme exists, config reference, lock busy, dirty paths, not a worktree, sync failed, verify failed, stale note, or I/O failure
  2  usage error

See docs/pomodoro-themes.md for the rename contract, refusal table, and revert runbook.

Put hidden Pomodoro themes back in Recent suggestion rows.

Each unhide appends one theme.unhide event to .bob/themes/<host>.jsonl under bob_sync.lock (wait at most 3s). A theme that is not hidden is a no-op.

Usage: bob themes unhide [OPTIONS] <NAME>...

Arguments:
  <NAME>...
          Theme name as it appears in a Pomodoro tail

Options:
  -b, --bob-dir <DIR>
          Bob vault root; defaults to BOB_DIR or ~/bob

  -f, --format <FORMAT>
          Output format: human or json

          [default: human]
          [possible values: human, json]

  -h, --help
          Show help

Examples:
  bob themes unhide BOOKS
  bob themes unhide FIXES -f json

Environment:
  BOB_CONFIG_FILE         Exact Bob config file; defaults to ~/.config/bob/config.yml
  BOB_DIR                   Bob vault root when --bob-dir is omitted
  BOB_NOW                   Local datetime override that pins the event timestamp
  HOSTNAME                  Host label for the journal file; same slug vault-sync uses
  BOB_VAULT_SYNC_LOCK_FILE  Maintenance lock; defaults to ${XDG_RUNTIME_DIR:-/tmp}/bob_sync.lock

Exit codes:
  0  wrote the unhide event
  1  unknown theme, unchanged, lock busy, or I/O failure
  2  usage error

See docs/pomodoro-themes.md for hide semantics and the journal contract.