Command Reference

Complete reference for all wsb command-line options and usage patterns.

Commands Overview

All tools are subcommands of the wsb binary:

wsb <COMMAND> [OPTIONS]

Command	Description
`refactor`	Recursive string replacement in files and directories
`git`	Git operations over the active scope
`template`	Tera template management
`update`	Update version and render templates
`wsbtemplate`	Cross-project `.wstemplate` version stamping
`version`	Database-driven version management
`scrap`	Local trash can using `.scrap` folder
`unscrap`	Restore files from `.scrap` folder
`ldiff`	Line difference visualization
`code`	AST-based code analysis and transformation
`test`	Intelligent test runner based on project type
`status`	Project status with feature metrics
`feature`	Feature management with state machine workflow
`task`	Feature-centric task management
`directive`	Project directive and rule management
`note`	Note management for any entity
`relationship`	Entity relationship management
`start`	Start development session
`end`	End development session
`continuity`	Session continuity and context management
`consolidate`	Documentation consolidation
`database`	Database backup, recovery, maintenance
`serve`	Web server for Claude AI integration
`sample`	Create sample project with test data

wsb refactor

Recursive string replacement in file names and contents with collision detection.

Synopsis

wsb refactor <ROOT_DIR> <OLD_STRING> <NEW_STRING> [OPTIONS]

Required Arguments

Argument	Description
`ROOT_DIR`	Root directory to search in (use `.` for current directory)
`OLD_STRING`	String to find and replace
`NEW_STRING`	Replacement string

Options

Option	Short	Description	Default
`--assume-yes`	`-y`	Skip confirmation prompts	`false`
`--force`	`-f`	Skip confirmation prompt	`false`
`--verbose`	`-v`	Show detailed output	`false`
`--backup`	`-b`	Create backup files before modifying	`false`
`--follow-symlinks`		Follow symbolic links	`false`
`--files-only`		Only process files (skip directories)	`false`
`--dirs-only`		Only process directories (skip files)	`false`
`--names-only`		Skip content replacement, only rename	`false`
`--content-only`		Skip renaming, only replace content	`false`
`--include <PATTERN>`		Include only files matching glob (repeatable)	all
`--exclude <PATTERN>`		Exclude files matching glob (repeatable)	none
`--max-depth <N>`		Maximum depth to search (0 = unlimited)	`0`
`--threads <N>`	`-j`	Number of threads (0 = auto)	`0`
`--ignore-case`	`-i`	Case-insensitive matching	`false`
`--regex`	`-r`	Use regex patterns	`false`
`--format <FORMAT>`		Output format: `human`, `json`, `plain`	`human`
`--progress <MODE>`		Progress display: `auto`, `always`, `never`	`auto`

Only one mode flag (--files-only, --dirs-only, --names-only, --content-only) can be specified at a time.

Examples

wsb refactor . "oldname" "newname"                          # Full replacement
wsb refactor . "oldname" "newname" --verbose                # Preview first
wsb refactor . "oldname" "newname" --include "*.rs" --backup
wsb refactor . "old.api.com" "new.api.com" --content-only
wsb refactor . "OldClass" "NewClass" --names-only
wsb refactor . "old_\\w+" "new_name" --regex
wsb refactor . "oldname" "newname" --format json            # Machine-readable output

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Invalid arguments
`3`	Permission denied
`4`	File not found
`5`	Naming collision detected

Git Operations (active scope)

Git operations run on the active git scope. If the current working directory contains .gitmodules, commands apply to the fleet rooted there; otherwise they apply to the current repository only.

Commands

Command	Description	Options
`wsb status`	Show git status for the active scope	`--verbose`
`wsb checkout`	Switch branch in the active scope	`--create`, `--ignore-missing`, `--verbose`, `--dry-run`
`wsb pull`	Pull only repositories whose remote branch is ahead of local HEAD	`--rebase`, `--force-all`, `--verbose`, `--dry-run`
`wsb push`	Push only repositories with outgoing commits	`--force-with-lease`, `--force-all`, `--verbose`, `--dry-run`
`wsb create`	Create a branch only in repositories with worktree changes	`--from`, `--push`, `--force-all`, `--verbose`, `--dry-run`
`wsb commit`	Commit only repositories with worktree changes	`--message`, `--push`, `--force-all`, `--verbose`, `--dry-run`
`wsb fetch`	Fetch only repositories whose remote refs differ from local remote-tracking refs	`--all`, `--force-all`, `--verbose`, `--dry-run`
`wsb stage`	Stage all changes in the active scope	`--verbose`, `--dry-run`
`wsb branch`	List branches in the active scope	`--all`, `--verbose`
`wsb diff`	Generate per-file diff files for the active scope	`--base`, `--since`, `--output`, `--staged`, `--verbose`
`wsb merge-back`	Merge the current branch back into the default branch	`--message`, `--verbose`, `--dry-run`
`wsb submodule-init`	Initialize submodules in the active scope	`--recursive`, `--verbose`, `--dry-run`

Examples

wsb status                              # Status for repo or fleet root
wsb checkout feature/my-change         # Switch branch
wsb create feature/my-change --push    # Create and push a branch
wsb commit -m "Implement feature"      # Commit current changes
wsb push --force-all                   # Push every repository, preserving legacy behavior
wsb diff --since 2d                    # Diff all changes since 2 days ago
wsb merge-back                         # Merge current branch into default branch

wsb template

Tera template management for automatic file generation during wsb update.

Subcommands

Subcommand	Description
`add`	Add a new template
`list`	List all templates
`show`	Show template details
`update`	Update an existing template
`delete`	Remove a template
`render`	Render all enabled templates

Examples

wsb template add version-header --template "v" --output version.h
wsb template list
wsb template show version-header
wsb template render
wsb template delete version-header

wsb update

Update version file and render all templates (both .tera and .wstemplate).

Synopsis

wsb update [OPTIONS]

Options

Option	Description	Default
`--no-git`	Skip git integration	`false`
`--git-add`	Auto-add updated files to git staging	`false`

What It Does

Calculates the current version from git history
Writes version.txt
Updates project files (Cargo.toml, package.json, etc.) with the new version
Renders .tera templates via the template manager
Renders .wstemplate files via the wstemplate engine
With --git-add: stages version.txt, rendered .tera outputs, and rendered .wstemplate outputs

Examples

wsb update                   # Basic update
wsb update --git-add         # Update and stage files
wsb update --no-git          # Update without git integration

wsb wstemplate

Manage .wstemplate file rendering for cross-project version stamping.

Each project has a single wstemplate entry consisting of an alias (Tera identifier) and a scan root (directory tree to search). Cross-project references like `` are resolved dynamically by scanning the root for sibling .wsb/state.json files.

Subcommands

Subcommand	Description
`add <PATH>`	Set the scan root (replaces any existing entry)
`remove <ALIAS>`	Remove this project’s wstemplate entry
`list-entries`	Show this project’s wstemplate entry
`list`	List all `.wstemplate` files relevant to this project
`render`	Render all relevant `.wstemplate` files
`vars [ALIAS]`	Show every template variable with its resolved value

Options for `add`

Option	Description
`--alias <ALIAS>`	Override auto-derived alias (must be valid Tera identifier)

Options for `vars`

Option	Description
`--remote`	Also resolve the fields that contact the remote

Template Variables

| Variable | Description | |———-|————-| describes the project that owns the template file. exposes the same fields for any project in the workspace — including every submodule, since each is a project in its own right.

Run wsb wstemplate vars to print this table with the current values resolved, or wsb wstemplate vars <alias> for another project.

Identity

Variable	Description
``	The alias itself
``	Project name from its `.wsb/state.json`
``	Absolute path to the project root
``	Path from the workspace root, e.g. `ext/gtest`

Calculated version — the version being built

Variable	Description
``	Full version from `version.txt`, e.g. `1.649.0`
``	Major component, prefixed, e.g. `v1`
``	Minor component, as a number
``	Patch component, as a number

Published tags — what actually exists to depend on

Variable	Description
``	Highest tag in this clone, verbatim, e.g. `v1.648.6494`
``	`latest_tag` without its leading `v` — the pin-ready form
``	Newest tag reachable from HEAD (`git describe`)
``	Number of tags, as a number
``	Highest tag that exists on the remote (contacts the network)
``	That tag without its leading `v` (contacts the network)

Head state

Variable	Description
``	Full HEAD commit hash
``	Abbreviated HEAD commit hash (7 characters)
``	HEAD commit date as YYYY-MM-DD
``	HEAD commit timestamp as RFC 3339
``	Checked-out branch name
``	Whether HEAD is detached, as a boolean
``	Whether the worktree has uncommitted changes, as a boolean
``	Name of the remote the project publishes to
``	Fetch URL of that remote

Render time

Variable	Description
``	RFC 3339 timestamp
``	YYYY-MM-DD
``	HH:MM:SS
``	Year
``	Month
``	Day
``	Seconds since the Unix epoch, as a number

`version` versus `latest_version`

version is the version being produced. version.txt is bumped on commit, so it is normally one step ahead of anything published — stamping it into a pin that an outside consumer has to resolve yields a reference to a release that does not exist yet. Use latest_version for those, and version for references resolved from a local checkout inside the workspace.

latest_tag reports what this clone knows; latest_remote_tag asks the remote and is therefore unaffected by how stale the clone is. Only the two remote tag fields touch the network, and only when a template references them.

Fields that do not apply

A field is either a real value or an error naming the reason — never an empty string. A project with no tags has no latest_tag, and a template asking for one fails with “it has no tags” rather than stamping "" into a manifest. References are checked before rendering, so nothing is half-written.

Template Selection

When rendering, only templates satisfying at least one condition are rendered:

The template lives under the current project’s root (own templates)
The template’s text contains a reference to ``

Error Handling

Unresolvable alias: Hard error listing all known aliases
Unknown field: Hard error listing every field that exists
Field that does not apply: Hard error naming the project and the reason
Missing version.txt: Hard error with instructions to run wsb update in the dependency
Multiple wstemplate entries in state.json: Hard error (single-entry model enforced)

Examples

wsb wstemplate add /path/to/workspace              # Set scan root
wsb wstemplate add /path/to/workspace --alias mylib # Custom alias
wsb wstemplate list-entries                         # Show current entry
wsb wstemplate list                                 # Show relevant templates
wsb wstemplate render                               # Render templates
wsb wstemplate vars                                 # List variables and values
wsb wstemplate vars mylib --remote                  # ...for a peer, with remote tags
wsb wstemplate remove mylib                         # Remove entry

wsb version

Version management with database-driven major version and git-calculated components.

Version Format

{major}.{minor}.{patch} where:

Major: Set via wsb version major (stored in database)
Minor: Total commits in the repository
Patch: Total line changes (additions + deletions)

Subcommands

Subcommand	Description	Options
`show`	Display version breakdown	`--verbose`, `--format`
`major <N>`	Set major version number
`tag`	Create git tag with current version	`--prefix`, `--message`
`info`	Show calculation details	`--include-history`

Examples

wsb version show                          # Display version
wsb version show --verbose --format json  # Detailed JSON output
wsb version major 2                       # Set major to 2
wsb version tag                           # Create git tag
wsb version tag --prefix "release-"       # Custom tag prefix
wsb version info --include-history        # Show git history analysis

wsb scrap

Local trash can using a .scrap folder for files you want to remove safely.

Synopsis

wsb scrap [PATH...] [SUBCOMMAND] [OPTIONS]

Subcommands

Subcommand	Description	Options
`list`	List `.scrap` contents	`--sort name\\|date\\|size`
`clean`	Remove old items	`--days N`
`purge`	Remove all items	`--force`
`find`	Search for patterns	`--content`
`archive`	Create archive	`--output FILE`, `--remove`

Examples

wsb scrap temp.txt logs/                    # Move to .scrap
wsb scrap list --sort size                  # List contents
wsb scrap find "*.log"                      # Find files
wsb scrap clean --days 30                   # Remove old items
wsb scrap archive backup.tar.gz --remove    # Archive and remove
wsb scrap purge --force                     # Empty completely

wsb unscrap

Restore files from .scrap folder to their original locations.

Synopsis

wsb unscrap [NAME] [OPTIONS]

Options

Option	Description
`--to PATH`	Custom restoration path
`--force`	Overwrite existing files

Examples

wsb unscrap                           # Restore last item
wsb unscrap important_file.txt        # Restore specific file
wsb unscrap config.json --to backup/  # Restore to directory
wsb unscrap data.txt --force          # Overwrite existing

wsb ldiff

Process input lines, replacing repeated tokens with a substitute character to highlight differences.

Synopsis

wsb ldiff [SUBSTITUTE_CHAR]

Default substitute character: ░

Examples

echo -e "hello world\nhello universe" | wsb ldiff
tail -f /var/log/syslog | wsb ldiff
cat access.log | wsb ldiff "*"

wsb status

Display project status with feature metrics and progress tracking.

Options

Option	Description	Default
`--debug-mode`	Enable diagnostic output	`false`
`--include-features`	Include feature breakdown	`false`
`--include-metrics`	Include detailed metrics	`false`
`--format`	Output format: `human`, `json`, `summary`	`human`

Examples

wsb status
wsb status --include-features
wsb status --include-metrics --format json

wsb feature

Feature management with state machine workflow and validation.

Subcommands

Subcommand	Description
`add`	Add a new feature
`list`	List features with filters
`show`	Show feature details
`update`	Update feature status/properties

Examples

wsb feature add "User authentication"
wsb feature list --state implemented
wsb feature show F00001

wsb task

Feature-centric task management with automatic feature detection.

Subcommands

Subcommand	Description
`add`	Add a new task
`list`	List tasks with filters
`show`	Show task details
`update`	Update task status/properties
`complete`	Mark task as completed
`start`	Start working on a task
`block`	Mark task as blocked
`unblock`	Remove blocked status

Examples

wsb task add "Implement login" "Build the login page" --feature F00001
wsb task list --status pending
wsb task show T000001
wsb task start T000001
wsb task complete T000001 --evidence "Tests passing"

wsb directive

Project directive and rule management.

Subcommands

Subcommand	Description
`add`	Add a new directive
`list`	List directives
`show`	Show directive details
`update`	Update directive
`activate`	Activate a directive
`deactivate`	Deactivate a directive
`check`	Check directive compliance

wsb code

AST-based code analysis and codebase exploration.

Subcommands

Subcommand	Description
`tree`	Visual tree of codebase structure (default)
`search`	Search for AST patterns in source code

Options for `tree`

Option	Description	Default
`--depth N`	Maximum depth to display	`3`
`--hidden`	Show hidden files and directories	`false`
`--sizes`	Show file sizes	`false`
`--extensions`	Filter by file extensions (e.g., `rs,py,js`)	all
`--no-ignore`	Ignore .gitignore rules	`false`

Examples

wsb code                                # Show tree (default)
wsb code tree --depth 5 --sizes         # Deep tree with file sizes
wsb code tree --extensions rs,toml      # Only Rust files
wsb code search "fn main" --language rust

wsb test

Intelligent test runner that detects project type and runs appropriate tests.

Options

Option	Description	Default
`--dry-run`	Show test command without executing	`false`
`--install`	Install missing test runners	`false`

Examples

wsb test                     # Run tests for detected project type
wsb test --dry-run           # Show what would run
wsb test -- --nocapture      # Pass args to test runner

wsb start / wsb end

Session management for development workflow.

wsb init

wsb init                                 # Initialize a new workspace in the current directory
wsb init "Implement auth"                # Initialize and record the first task

wsb start

wsb start                                # Start new session
wsb start --continue-from T000001        # Continue from task
wsb start "Implement auth"               # Start with first task description

wsb end

wsb end                                  # End session
wsb end --summary "Completed auth"       # End with summary
wsb end --skip-docs                      # Skip documentation updates

wsb serve

Web server for Claude AI integration with automatic session management.

Options

Option	Description	Default
`--port`	HTTP server port	`3000`
`--debug`	Enable debug logging	`false`
`--migrate`	Migrate features from features.md to database	`false`

Examples

wsb                               # Start on localhost:3000
wsb serve --port 8080             # Custom port
wsb serve --debug                 # With debug logging

wsb database

Database backup, recovery, and maintenance operations.

wsb continuity

Session continuity and context management.

Subcommands

Subcommand	Description
`list`	List continuity records
`snapshot`	Create context snapshot

wsb consolidate

Documentation consolidation with diagram management.

Options

Option	Description
`--generate-diagrams`	Generate architectural diagrams in DOT format
`--preserve-complexity`	Preserve complexity information
`--force`	Force consolidation

Getting Help

wsb --help              # Show all commands
wsb <COMMAND> --help    # Help for specific command

Command Reference

Commands Overview

wsb refactor

Synopsis

Required Arguments

Options

Examples

Exit Codes

Git Operations (active scope)

Commands

Examples

wsb template

Subcommands

Examples

wsb update

Synopsis

Options

What It Does

Examples

wsb wstemplate

Subcommands

Options for add

Options for vars

Template Variables

version versus latest_version

Fields that do not apply

Template Selection

Error Handling

Examples

wsb version

Version Format

Subcommands

Examples

wsb scrap

Synopsis

Subcommands

Examples

wsb unscrap

Synopsis

Options

Examples

wsb ldiff

Synopsis

Examples

wsb status

Options

Examples

wsb feature

Subcommands

Examples

wsb task

Subcommands

Examples

wsb directive

Subcommands

wsb code

Subcommands

Options for tree

Examples

wsb test

Options

Examples

wsb start / wsb end

wsb init

wsb start

wsb end

wsb serve

Options

Examples

wsb database

wsb continuity

Subcommands

wsb consolidate

Options

Getting Help

Options for `add`

Options for `vars`

`version` versus `latest_version`

Options for `tree`