Skip to content

bwrb bulk

Perform batch operations on multiple notes with targeting and safety gates.

Terminal window
bwrb bulk [options] [target]

The target argument is auto-detected as type, path (contains /), or where expression.

OptionDescription
-t, --type <type>Filter by type
-p, --path <glob>Filter by file path (supports globs)
-w, --where <expr>Filter by frontmatter expression (repeatable, ANDed)
-b, --body <query>Filter by Markdown body content; YAML frontmatter is excluded
-a, --allTarget all files (requires explicit intent)
OptionDescription
--set <field>=<value>Set field value (or clear with --set field=)
--rename <old>=<new>Rename field
--delete <field>Delete field
--append <field>=<value>Append to list field
--remove <field>=<value>Remove from list field
--move <path>Move files to path (auto-updates wikilinks)
OptionDescription
-x, --executeActually apply changes (dry-run by default)
-f, --forceSkip confirmation prompt for large/cross-type operations
-y, --yesAlias for --force (skip confirmation)
--backupCreate backup before changes
--limit <n>Limit to n files
OptionDescription
--verboseShow detailed changes per file
--quietOnly show summary
--output <format>Output format: text, json

In JSON mode, bulk output reports both discovery stages:

  • candidateFiles: files selected by type/path/body targeting before --where
  • matchedFiles / totalFiles: files remaining after all filters
  • filesModified: files that would change or did change

Bulk operations require two explicit gates to prevent accidents:

  1. Targeting gate: Specify selectors (--type, --path, --where, --body) OR use --all
  2. Execution gate: Use --execute to apply changes (dry-run by default)
Terminal window
# Error: no targeting specified
bwrb bulk --set status=settled
# "No files selected. Use --type, --path, --where, --body, or --all."
# Dry-run: shows what would change
bwrb bulk --type task --set status=settled
# Actually applies changes
bwrb bulk --type task --set status=settled --execute

When a change enters a trait-configured guarded transition, bulk evaluates the same relation requirements as edit. Each blocked file is reported as an error and remains unchanged; dry-runs report the block too.

Bulk also validates and applies entered transition_effects with the same source-and-target lock and byte checks as edit. A target effect is direct and non-cascading; dry-runs surface invalid target patches before reporting a change.

If stdin is not a TTY and the operation requires confirmation (cross-type --all or large operations), bwrb does not prompt. Use --force/--yes to skip the confirmation or pipe a single y/yes or n/no answer. Otherwise the command fails fast with a clear error.

Terminal window
# Set field on matching notes
bwrb bulk --type task --where "status == 'in-flight'" --set status=settled --execute
# Clear a field
bwrb bulk --type task --set old_field= --execute
# Set multiple fields
bwrb bulk --type task --where "status == 'settled'" --set archived=true --set "archived-date=2025-01-15" --execute
Terminal window
# Rename a field
bwrb bulk --all --rename old-field=new-field --execute
# Delete a field
bwrb bulk --type task --delete legacy_field --execute
Terminal window
# Append to a list field
bwrb bulk --type task --where "priority == 'high'" --append tags=urgent --execute
# Remove from a list field
bwrb bulk --type task --remove tags=deprecated --execute
Terminal window
# Move files to archive (updates wikilinks automatically)
bwrb bulk --type idea --where "status == 'settled'" --move Archive/Ideas --execute

An executed move takes the same per-note locks as edit on the notes it writes: each moved note at its old path and at its new path inside the vault, and every note whose links it rewrites. An edit of one of those notes waits until the move is done. Under the locks, the move scans the vault for links again. If a note gained a link to a moved note while the move waited, the move locks that note too and tries again. After three tries it stops with an error, having moved nothing.

Terminal window
# By type
bwrb bulk --type task --set status=settled --execute
# By path
bwrb bulk --path "Archive/**" --set archived=true --execute
# By content
bwrb bulk --body "TODO" --set needs-review=true --execute
# By frontmatter
bwrb bulk --where "status == 'active' && priority < 3" --set urgent=true --execute
# All files
bwrb bulk --all --set reviewed=true --execute
Terminal window
# Create backup before changes
bwrb bulk --type task --all --set status=archived --execute --backup
# Limit scope
bwrb bulk --type task --set status=settled --execute --limit 10
# Preview with verbose output
bwrb bulk --type task --set status=settled --verbose
Terminal window
# Bulk-add type to existing files by location
bwrb bulk --path "Reflections/Daily Notes" --set type=daily-note --execute
# Find files with legacy frontmatter
bwrb list --where "!isEmpty(old_field)"
# Warning: 'old_field' not in schema
# Rename field across all notes of a type
bwrb bulk --type task --rename old_field=new_field --execute