wsb

Multi-tool CLI suite for file operations, version management, and development workflow automation. All tools accessible through a single wsb binary, with wsb-daemon beside it serving the workbench.

Install

wsb starts wsb-daemon from its own directory, so the two are installed together:

cargo install wsb wsb-daemon

Or build from source (./dx build also builds the macOS app around them):

git clone https://github.com/jowharshamshiri/wsb.git
cd wsb/wsb
cargo install --path . && cargo install --path daemon

Building wsb-daemon builds its workbench frontend too, so it needs Node.js (^20.19, ^22.12 or >=24) and npm >=10.2.3.

Core Tools

Command	Description
`wsb refactor`	Recursive string replacement in files and directories
`wsb scrap`	Local trash can with `.scrap` folder
`wsb unscrap`	Restore files from `.scrap` folder
`wsb ldiff`	Line difference visualization for pattern analysis
`wsb status`, `wsb stage`, `wsb commit`, `wsb push`, etc.	Git operations over the current repo or fleet root
`wsb discard`	Throw away local changes across every worktree, after showing what would go
`wsb each`	Run a shell script once for each submodule
`wsb update`	Update version file and render all templates
`wsb template`	Tera template management (add, list, show, enable, remove, render)
`wsb wstemplate`	Cross-project version stamping with `.wstemplate` files
`wsb local`	Point every manifest in the fleet at the working copies here, or take that back
`wsb checkpoint`	Take the local render back, commit the fleet, push, and go local again
`wsb version`	Version management (show, major, tag, info)
`wsb code`	AST-based code analysis and transformation
`wsb test`	Intelligent test runner based on project type
`wsb catalog`	The workspace's test catalogue: numbering, duplicates, parity between families
`wsb note`, `wsb relationship`, `wsb continuity`, `wsb database`	Notes, entity links, session continuity, database maintenance
`wsb serve`	Start the workbench: make sure the machine's `wsb-daemon` is running and print this workspace's page
`wsb daemon`	The machine's daemon: what it is serving, stopping and restarting it, its log, running it as a service
`wsb peer`	Pair with another machine and carry this workspace's working tree to it, without a commit
`wsb init`, `wsb check`, `wsb workspace`	A workspace's own files: create, verify, bring up to date
`wsb github`	Issues, pull requests, CI, gists and every Projects board of your account and organisations, from one mirror per machine (also `wsb-github`)
`wsb compact`	Compact a session transcript by removing low-signal noise
`wsb ignore`, `wsb last-hash`, `wsb audit-path`, `wsb completions`, `wsb sample`	Utilities: a `.gitignore` line in every subdirectory, a file's last commit, shadowed executables on `PATH`, shell completions, a sample project

Run wsb with no command to start the workbench (wsb serve).

Quick Start

# Recursive string replacement
wsb refactor ./src "OldClassName" "NewClassName" --verbose

# Safe file disposal and recovery
wsb scrap temp_files/ experimental/
wsb unscrap important_config.toml

# Git operations over the current repo or fleet root
wsb status
wsb checkout feature/my-change

# Cross-project version stamping
wsb wstemplate add /path/to/workspace-root
wsb wstemplate render

# Line difference visualization
tail -f /var/log/app.log | wsb ldiff

# The workbench: every workspace on the machine, in the browser
wsb serve

Version Management

wsb uses a three-part versioning scheme: {major}.{minor}.{patch}

Major: Set via wsb version major (kept in the workspace database)
Minor: The commits of the repository and of every initialised submodule under it
Patch: The file changes since the newest release tag of that major

Version can be stamped into project files (Cargo.toml, package.json, pyproject.toml, etc.) via wsb update.

Cross-Project Version Stamping

.wstemplate files are Tera templates that render to the file with the suffix stripped (e.g., Cargo.toml.wstemplate renders to Cargo.toml). Templates can reference any sibling project's version:

[package]
name = "my-app"
version = "{{ project.version }}"

[dependencies]
my-lib = { path = "../my-lib", version = "{{ projects.my_lib.version }}" }

Templates see more than the version. Each project — every submodule included — also exposes its newest published tag, HEAD commit, branch, worktree state, and path within the workspace:

[dependencies]
# Resolved from a local checkout: the version being built is the right one
my-lib = { path = "../my-lib", version = "{{ projects.my_lib.version }}" }
# Resolved from a registry by someone outside the workspace: must name a release
# that exists, and `version` is bumped on commit so it is always one step ahead
my-dep = "{{ projects.my_dep.latest_version }}"

Run wsb wstemplate vars to list every variable with its current value. A field that does not apply is an error naming the reason, never an empty string — a project with no tags fails the render instead of stamping "".

Cross-project references are resolved dynamically by scanning for .wsb/state.json files — no explicit dependency declarations needed.

Configuration

Committed with the workspace, one file per tool, each refusing keys it does not know. wsb init excludes .wsb/ from git on the machine, so add these with git add -f:

File	What it declares
`.wsb/stamp.json`	For templates: `declared` (a JSON file `{{ declared.… }}` reads), `build_root` (`{{ build.root_from_here }}`), and `local` — the `variable` that selects the local render, with optional `prepare`/`release` commands for `wsb local` and `wsb checkpoint`
`.wsb/test.json`	`parity_families`: which repositories hold the same numbered tests, for `wsb catalog parity <family>`
`.wsb/peer.json`	`continuity`: `include_ignored` and `exclude` path prefixes — what continuity carries to a paired machine beyond what git tracks or would track, and what it leaves alone

The boards a project references live outside any checkout, in $PRJ/<project>/.wsb/github.json (see the GitHub Guide).

.wsb/state.json marks a workspace. One written by an older wsb, naming its own place, is brought up to date with wsb workspace relocate-state.

Documentation

License

MIT

wsb 0.253.6349

wsb