bob relations¶

List, hide, unhide, and rename relation labels

Bare `bob relations` runs the read-only list. hide and unhide append to the vault journal; rename commits one verified vault rewrite.

Usage: bob relations [COMMAND]

Commands:
  hide    Hide relation labels from suggestions
  list    List relation labels in the vault (default)
  rename  Rename a relation label everywhere in one commit
  unhide  Show hidden relation labels in suggestions again

Options:
  -h, --help  Print help

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

Examples:
  bob relations                      Visible labels, most-used first
  bob relations -q insp -f json      Rank inspiration matches as JSON
  bob relations -a                   Include hidden labels
  bob relations hide "inspired by"   Hide a label from suggestions
  bob relations rename OLD NEW       Rename a label everywhere
  bob relations unhide "inspired by" Put a label back in suggestions

See docs/task-relations.md for the label-vocabulary contract.
Run 'bob relations <command> --help' for more information on a command.

Hide one or more relation labels from suggestions only: the card rows, the Obsidian stage, `relations list` defaults, and shell completion. LINKS text, LINKED FROM mirrors, chips, counts, and typed use are unchanged, and using a hidden label never unhides it.

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

Usage: bob relations hide [OPTIONS] <LABEL>...

Arguments:
  <LABEL>...
          Relation label as it appears on a LINKS entry

Options:
      --allow-unused
          Hide a label the catalog has not seen yet

  -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 relations hide "inspired by"
  bob relations hide "inspired by" implements -f json
  bob relations hide "brand new" --allow-unused

Environment:
  BOB_CONFIG_FILE         Exact Bob config file; defaults to ~/.config/bob/config.yml
  BOB_DIR                   Bob vault root when --bob-dir is omitted
  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 label, invalid label, unchanged, lock busy, or I/O failure
  2  usage error

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

List the relation-label vocabulary derived from every LINKS entry in the vault: open, closed, done/, daily notes, nested projects, and references. The catalog is read-only: it never writes the vault. Bare `bob relations` runs this command.

By default the list shows visible labels, most-used first. Hidden labels stay out of the default list; they still label their links. Use --all to include every known label, --hidden to show only hidden labels, --query to rank exact/prefix matches before substring matches.

Usage: bob relations list [OPTIONS]

Options:
  -a, --all
          List every known label, 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]

  -h, --help
          Show help

  -H, --hidden
          List only hidden labels

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

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

Examples:
  bob relations
  bob relations list
  bob relations -q insp -f json
  bob relations -a
  bob relations -H
  bob relations -n 10 -q dup

Environment:
  BOB_CONFIG_FILE         Exact Bob config file; defaults to ~/.config/bob/config.yml
  BOB_DIR                   Bob vault root when --bob-dir is omitted
  NO_COLOR                  Disable colored output

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

See docs/task-relations.md for the label-vocabulary contract.

Rename one relation label across every task note, including done/ and the previous daily note, in one verified Git commit. Only label spans on LINKS and LINKED FROM lines change; entries keep their order and every other byte is preserved.

The preview scans the current vault. A write takes bob_sync.lock, pre-syncs unless --offline, snapshots each target and compares again before writing, appends one relation_label.rename event, verifies the result, makes one commit, then post-syncs. Undo with git revert.

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

Arguments:
  <OLD>
          Current relation label

  <NEW>
          New relation label

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 relations rename "inspired by" "prompted by" -d
  bob relations rename "inspired by" "prompted by" -d -f json
  bob relations rename old new --merge
  bob relations rename old new -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
  HOSTNAME                  Host label for the journal file; same slug vault-sync uses
  BOB_VAULT_SYNC_LOCK_FILE  Maintenance lock; defaults to the runtime bob_sync.lock

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

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

Put hidden relation labels back in suggestion rows.

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

Usage: bob relations unhide [OPTIONS] <LABEL>...

Arguments:
  <LABEL>...
          Relation label as it appears on a LINKS entry

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 relations unhide "inspired by"
  bob relations unhide "inspired by" -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
  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 label, invalid label, unchanged, lock busy, or I/O failure
  2  usage error

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