# wsb
[](https://crates.io/crates/wsb)
[](https://crates.io/crates/wsb)
[](https://crates.io/crates/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:
```bash
cargo install wsb wsb-daemon
```
Or build from source (`./dx build` also builds the macOS app around them):
```bash
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
| `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
```bash
# 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
# 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:
```toml
[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:
```toml
[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`:
| `.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
- [Installation Guide](https://jowharshamshiri.github.io/wsb/installation/)
- [Getting Started](https://jowharshamshiri.github.io/wsb/getting-started/)
- [Usage Guide](https://jowharshamshiri.github.io/wsb/usage/)
- [State Guide (Versioning & Wstemplate)](https://jowharshamshiri.github.io/wsb/state-guide/)
- [GitHub Guide](https://jowharshamshiri.github.io/wsb/github-guide/)
- [Daemon and Workbench](https://jowharshamshiri.github.io/wsb/daemon/)
- [Peer Guide](https://jowharshamshiri.github.io/wsb/peer-guide/)
- [Command Reference](https://jowharshamshiri.github.io/wsb/api-reference/)
- [Testing](https://jowharshamshiri.github.io/wsb/testing/)
## License
MIT