workbench CLI

A terminal UI for initializing a workbench repository — fork, clone, and wire up git submodules interactively or non-interactively.

Prerequisites

• Bun installed
• gh CLI installed and authenticated (gh auth login)

Installation

cd packages/workbench-cli
bun install
bun link

After linking, the workbench command is available globally.

Run without installing

bun run src/index.ts

Quick start

Interactive (TUI)

workbench --init

Launches an interactive flow: select a fork target (org or personal account), name your workbench, fork and clone the template repo, then optionally run the setup wizard.

Non-interactive

workbench --init --no-tui --name my-project

Init + setup in one command

workbench --init --no-tui --name my-project --org myorg --code-repository https://github.com/myorg/api

Existing repo

If you already have a workbench repo cloned:

workbench --tui

Init flags

| Flag | Description | Default | |------|-------------|---------| | --init | Initialize a new workbench (fork & clone) | false | | --name <name> | Name for the fork and local folder | workbench | | --no-fork | Clone without forking (read-only) | false | | --no-tui | Skip TUI, use defaults or provided values | false |

Setup flags

These flags work with both --init and standalone usage:

| Flag | Description | Default | |------|-------------|---------| | --org <name> | GitHub organization name | personal account | | --code-repository <url> | Code repository URL (can be repeated) | — | | --resource-repository <url> | Resource repository URL (can be repeated) | — | | --code-branch <name> | Branch for all code repositories | main | | --resource-branch <name> | Branch for all resource repositories | main | | --index <on\|off> | Run ck indexing after init | on | | --tui | Launch interactive TUI mode | false |

What is ck? ck is a hybrid code search tool by BeaconBay that fuses lexical (BM25/grep) precision with embedding-based recall, so you can find the right code even when the exact keywords aren't there.

Examples

# Interactive init
workbench --init

# Non-interactive init with custom name
workbench --init --no-tui --name my-project

# Clone without forking (read-only)
workbench --init --no-tui --no-fork --name explore-wb

# Init + setup in one command
workbench --init --no-tui --name my-project --org myorg --code-repository https://github.com/myorg/api

# Standalone setup (existing repo)
workbench --org myorg --code-repository https://github.com/myorg/backend

# Interactive setup (existing repo)
workbench --tui

What the setup wizard does

Running init walks through:

1. Select a GitHub organization or personal account.
2. Select code repositories — added as submodules under projects/.
3. Select resource repositories — added as submodules under resources/.
4. Configure the target branch per repository.
5. Optionally index with ck.

Afterwards, .workbench/config.yaml is written with the selected configuration.

Error scenarios

| Error | Cause | Resolution | |-------|-------|------------| | A repository named "X" already exists under Y | Fork name conflict | Choose a different --name | | A folder named "X" already exists in the current directory | Local folder conflict | Remove or rename the folder, or choose a different name | | gh CLI is not authenticated | gh auth not set up | Run gh auth login | | Invalid name "X" | Bad characters in name | Use only alphanumeric, -, ., _ |

Development

# Type-check
bun tsc --noEmit

# Build
bun run build

# Smoke test the built output
./dist/index.js --help

Source lives in src/. The entry point is src/index.ts.

Releases

Releases are tag-driven and publish to both npm and JSR automatically. Maintainers run:

npm run release:patch   # 0.1.x
npm run release:minor   # 0.x.0
npm run release:major   # x.0.0

See GitHub Releases for the version history.

Contributing

See CONTRIBUTING.md for the full guide.

License

MIT — see LICENSE.