bwrb bulk

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

Synopsis

bwrb bulk [options] [target]

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

Options

Targeting

Option	Description
-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, --all	Target all files (requires explicit intent)

Operations

Option	Description
--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)

Execution

Option	Description
-x, --execute	Actually apply changes (dry-run by default)
-f, --force	Skip confirmation prompt for large/cross-type operations
-y, --yes	Alias for --force (skip confirmation)
--backup	Create backup before changes
--limit <n>	Limit to n files

Output

Option	Description
--verbose	Show detailed changes per file
--quiet	Only 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

Safety: Two-Gate Model

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)

# 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.

Non-interactive Confirmation

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.

Examples

Set Operations

# 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

Field Management

# Rename a field
bwrb bulk --all --rename old-field=new-field --execute

# Delete a field
bwrb bulk --type task --delete legacy_field --execute

List Field Operations

# 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

File Movement

# Move files to archive (updates wikilinks automatically)
bwrb bulk --type idea --where "status == 'settled'" --move Archive/Ideas --execute

Targeting

# 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

Safety Options

# 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

Migration Workflows

# 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

See Also

• CLI Safety and Flags — --execute vs --force semantics
• Targeting Model — Full selector reference
• bwrb audit — Validate notes
• bwrb delete — Delete notes