bob types¶

Manage task types and explain task suggestions

Bare `bob types` runs the read-only list. hide, unhide, color, and rename append to the vault journal. migrate rewrites legacy theme spellings in one commit.

Usage: bob types [COMMAND]

Commands:
  color    Pin or unpin a type's hue
  hide     Hide types from Recent suggestion rows
  list     List remembered task types (default)
  migrate  Rewrite legacy theme spellings to type in one commit
  rename   Rename a task type everywhere in one commit
  split    Split one task type across selected entries in one commit
  suggest  Explain the suggested type for a task or capture route
  unhide   Show hidden types in Recent suggestion rows again

Options:
  -h, --help  Print help

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

Examples:
  bob types                   Visible types from the last 90 days
  bob types -q fix -f json    Rank FIX before FIXES as JSON
  bob types hide BOOKS        Hide BOOKS from Recent rows
  bob types unhide BOOKS      Put BOOKS back in Recent rows
  bob types color BLOG red    Pin BLOG to red
  bob types color BLOG auto   Drop the BLOG pin
  bob types migrate -d            Preview rewriting theme: and [theme::]
  bob types rename FIXES FIX -d   Preview a global rename
  bob types split JOB -t > job.tsv
  bob types split JOB -m job.tsv -d
  bob types suggest dev:build    Explain a task’s suggested type

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

Pin a task type to a palette slot, or pass auto to drop the pin so the hue rule (config, pin, exempt, unconfigured, 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. A type whose color comes from the `themes:` block refuses with `config_color`: edit the config file instead.

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

Arguments:
  <NAME>
          Task type name as it appears in a Pomodoro name

  <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 types color BLOG red
  bob types color BLOG auto
  bob types 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 type, invalid hue, unchanged, config color, lock busy, or I/O failure
  2  usage error

Refusal codes: `unknown_theme`, `invalid_hue`, `unchanged`, `config_color`, `lock_busy`, `io`.

See docs/task-types.md for the hue rule and the journal contract.

Hide one or more task types 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 type that is already hidden is a no-op.

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

Arguments:
  <NAME>...
          Task type name as it appears in a Pomodoro name

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 types hide BOOKS
  bob types hide FIXES BOOKS -f json
  bob types 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 type, unchanged, lock busy, or I/O failure
  2  usage error

See docs/task-types.md for hide semantics and the journal contract.

List task types derived from canonical daily notes.

A task type names the kind of work a task represents; a Pomodoro name may contain several type components. The catalog is read-only: it never writes the vault. Bare `bob types` runs this command.

By default the list shows visible types used in the last 90 days or today, newest first. Hidden types stay out of the default list; they still exist in history, Stats, and colors. Use --all to include every known type, --hidden to show only hidden types, --query to rank exact/prefix matches before substring matches, and --fresh to ignore the machine-local cache. When a `themes:` vocabulary is configured in the config file, the default list also shows every visible configured type, even ones never used.

Usage: bob types list [OPTIONS]

Options:
  -a, --all
          List every known type, 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 and note-default facts, ignoring caches

  -h, --help
          Show help

  -H, --hidden
          List only hidden types

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

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

Examples:
  bob types
  bob types list
  bob types -q fix -f json
  bob types -a -F
  bob types -H
  bob types -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/task-types.md for identity, cache, hue, JSON, and journal writers.

Rewrite open-task `[theme::]` / `(theme::)` fields to `[type::]` / `(type::)` and area/project `theme:` defaults to `task_type:` in a single verified Git commit.

Each rewritten field keeps its bracket or paren form, spacing around `::`, and value bytes. Each rewritten default keeps its value bytes and quote style. When a note already has `task_type:`, a matching `theme:` line is removed; a different value is reported as `conflict` and left alone. Closed tasks, `done/`, repair-state lines, prose, fenced examples, `.bob/`, and `_conflicts/` are never touched. Repair lines are listed as `needs_repair`.

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, verifies that every changed line differs only in the key span (or is a removed matching `theme:` default), makes one commit, then post-syncs. Undo is `git revert`. When nothing is legacy, the command refuses with `unchanged` and does not commit.

Online writes require -b/--bob-dir and BOB_DIR (default ~/bob) to resolve to the same vault; a mismatch refuses before locks or sync. Set BOB_DIR to the selected vault or use --offline. Previews and offline writes do not require this match.

Usage: bob types migrate [OPTIONS]

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

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

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

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

  -h, --help
          Show help

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

Examples:
  bob types migrate -d
  bob types migrate -d -f json
  bob types migrate -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_VAULT_SYNC_LOCK_FILE  Maintenance lock; defaults to ${XDG_RUNTIME_DIR:-/tmp}/bob_sync.lock

Exit codes:
  0  migrated (or dry-run planned)
  1  unchanged, lock busy, dirty paths, not a worktree, sync failed, verify failed, stale note, or I/O failure
  2  usage error

See docs/task-types.md for the migrate contract and revert runbook.

Rename one task type across every canonical daily note (past, today, and future, open and closed) plus _templates/daily.md, area and project `task_type:` / `theme:` defaults, and `[type::]` / `(type::)` plus legacy `[theme::]` / `(theme::)` task fields (including done/), in a single verified Git commit.

Pomodoro ` — NAME` tails keep their `+` spelling, a resulting duplicate collapses (`FIX + FIXES` → `FIX`), and every other byte is preserved. Note defaults and task fields take NEW's spelling (with `--merge`, fields simply take NEW). Prose, fenced examples, `.bob/`, and `_conflicts/` are never touched.

The preview always rescans from source and counts sessions, defaults, and task types separately. 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`.

Online writes require -b/--bob-dir and BOB_DIR (default ~/bob) to resolve to the same vault; a mismatch refuses before locks or sync. Set BOB_DIR to the selected vault or use --offline. Previews and offline writes do not require this match.

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

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

  <NEW>
          New single type 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 types rename FIXES FIX -d
  bob types rename FIXES FIX -d -f json
  bob types rename OLD NEW --merge
  bob types 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 type, invalid name, unchanged, type 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/task-types.md for the rename contract, refusal table, and revert runbook.

Rewrite selected task type components in ` — NAME` tails of canonical daily notes (past, today, and future, open and closed) from a tab-separated map, in a single verified Git commit.

`-t/--template` prints a TSV map of every entry whose name contains OLD; it never takes the lock or writes. `_templates/daily.md` is out of scope. Fill the TYPE column (an untouched row keeps OLD), then apply with `-m/--map`. `-m -` reads the map from stdin.

Only the OLD component in mapped tails changes: separators keep their `+` spelling, a resulting duplicate collapses (`JOB + BUILD` with TYPE BUILD becomes `BUILD`), and every other byte is preserved. Unmapped OLD entries are left alone. Note defaults (`task_type:` / `theme:`) and `[type::]` / `(type::)` plus legacy `[theme::]` / `(theme::)` task fields are left unchanged; a `split_leaves_task_themes` warning reports leftover counts when OLD still appears there. Split writes no journal event: OLD keeps its hidden state and pin, and every target keeps its own.

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

Online writes require -b/--bob-dir and BOB_DIR (default ~/bob) to resolve to the same vault; a mismatch refuses before locks or sync. Set BOB_DIR to the selected vault or use --offline. Previews, templates, and offline writes do not require this match.

Usage: bob types split [OPTIONS] <--map <FILE>|--template> <OLD>

Arguments:
  <OLD>
          Type name to split, as it appears in a Pomodoro tail

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

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

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

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

  -h, --help
          Show help

  -m, --map <FILE>
          Tab-separated map of DATE, REF, TYPE; - reads stdin

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

  -t, --template
          Print a TSV map of OLD entries without writing

Examples:
  bob types split JOB -t > job.tsv
  bob types split JOB -m job.tsv -d
  bob types split JOB -m job.tsv -d -f json
  bob types split JOB -m - -o

Map format:
  # comment lines and blank lines are skipped
  DATE<TAB>REF<TAB>TYPE[<TAB>NOTE]
  DATE is YYYY-MM-DD; REF is LINE:DIGEST; TYPE is one + component; NOTE is ignored.

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
  HOSTNAME                  Host label vault-sync uses (split does not write a journal)
  BOB_VAULT_SYNC_LOCK_FILE  Maintenance lock; defaults to ${XDG_RUNTIME_DIR:-/tmp}/bob_sync.lock

Exit codes:
  0  split (or dry-run planned, or template printed)
  1  unknown type, invalid name, unchanged, stale entry, lock busy, dirty paths, not a worktree, sync failed, verify failed, stale note, or I/O failure
  2  usage error or invalid map

See docs/task-types.md for the split contract, map format, refusal table, and revert runbook.

Explain a task's suggested type without changing the vault.

Use route:block-id for an existing task, or a bare route for a new task's
default. Task fields take precedence over reading and note
defaults. Hidden and unknown types are reported; closed tasks have no suggestion.

Usage: bob types suggest [OPTIONS] <TARGET>

Arguments:
  <TARGET>
          Capture route or route:block-id (without @ or ^)

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 types suggest dev
  bob types suggest dev:build -f json

Environment:
  BOB_CONFIG_FILE  Exact Bob config file
  BOB_DIR          Vault root when --bob-dir is omitted
  BOB_NOW          Local datetime override
  NO_COLOR         Disable colored output

Exit codes:
  0  explanation (including no suggestion or a closed task)
  1  target lookup or I/O failure
  2  usage or config error

See docs/task-types.md for the suggestion contract.

Put hidden task types 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 type that is not hidden is a no-op.

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

Arguments:
  <NAME>...
          Task type name as it appears in a Pomodoro name

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 types unhide BOOKS
  bob types 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 type, unchanged, lock busy, or I/O failure
  2  usage error

See docs/task-types.md for hide semantics and the journal contract.