PAP-7015 Adds workbench --init command for setup

README.md

@@ -43,6 +43,32 @@ bun link
 bun run packages/workbench-cli/src/index.ts
 ```
 
+### Quick Start
+
+**Interactive init** — fork, clone, and set up in one flow:
+
+```bash
+workbench --init
+```
+
+**Non-interactive init** — create with defaults:
+
+```bash
+workbench --init --no-tui --name my-project
+```
+
+**Init + setup combined:**
+
+```bash
+workbench --init --no-tui --name my-project --org myorg --code-repository https://github.com/myorg/api
+```
+
+**Manual alternative** — fork/clone the repo yourself, then:
+
+```bash
+workbench --tui
+```
+
 ### Usage
 
 Run `workbench` from the workbench repository root. Select `init` to walk through:
@@ -53,4 +79,6 @@ Run `workbench` from the workbench repository root. Select `init` to walk throug
 4. Configure branch per repository
 5. Optionally index with `ck`
 
-After init, `.workbench/config.yaml` is written with the selected configuration.
+After init, `.workbench/config.yaml` is written with the selected configuration.
+
+See [packages/workbench-cli/README.md](packages/workbench-cli/README.md) for full documentation.

packages/workbench-cli/README.md

@@ -26,7 +26,95 @@ You can run the CLI directly from the source without linking:
 bun run src/index.ts
 ```
 
-## Usage
+## Quick Start
+
+### Interactive (TUI)
+
+Create a new workbench from scratch:
+
+```bash
+workbench --init
+```
+
+This 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
+
+Create a workbench without prompts:
+
+```bash
+workbench --init --no-tui --name my-project
+```
+
+### Combined (init + setup in one command)
+
+```bash
+workbench --init --no-tui --name my-project --org myorg --code-repository https://github.com/myorg/api
+```
+
+### Manual Setup
+
+If you already have a workbench repo cloned:
+
+```bash
+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 indexing after init | `on` |
+| `--tui` | Launch interactive TUI mode | `false` |
+
+## Examples
+
+```bash
+# 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
+```
+
+## 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, `-`, `.`, `_` |
+
+## Usage (Existing Repo)
 
 Run the `workbench` command from the workbench repository root. Select `init` to walk through the interactive setup:
 

packages/workbench-cli/src/args.ts

@@ -9,6 +9,10 @@ export interface CliArgs {
   codeBranch: string
   resourceBranch: string
   index: boolean
+  init: boolean
+  noFork: boolean
+  name: string
+  noTui: boolean
 }
 
 export function parseCliArgs(): CliArgs {
@@ -22,6 +26,10 @@ export function parseCliArgs(): CliArgs {
       "code-branch": { type: "string", default: "main" },
       "resource-branch": { type: "string", default: "main" },
       index: { type: "string", default: "on" },
+      init: { type: "boolean", default: false },
+      "no-fork": { type: "boolean", default: false },
+      name: { type: "string", default: "workbench" },
+      "no-tui": { type: "boolean", default: false },
     },
     strict: true,
     allowPositionals: false,
@@ -36,20 +44,29 @@ export function parseCliArgs(): CliArgs {
     codeBranch: values["code-branch"] as string,
     resourceBranch: values["resource-branch"] as string,
     index: values.index === "on",
+    init: values.init,
+    noFork: values["no-fork"] as boolean,
+    name: values.name as string,
+    noTui: values["no-tui"] as boolean,
   }
 }
 
 export function printHelp(): void {
   console.log(`workbench - Initialize a development workbench
 
 USAGE:
-  workbench --org <name> --code-repository <url> [--code-repository <url>...] [options]
-  workbench --org <name> --resource-repository <url> [--resource-repository <url>...] [options]
+  workbench --init [options]
+  workbench --init --no-tui [options]
+  workbench --org <name> --code-repository <url> [options]
   workbench --tui
   workbench --help
 
 OPTIONS:
-  --org <name>                    GitHub organization name (required for non-interactive)
+  --init                          Initialize a new workbench (fork & clone)
+  --name <name>                   Name for the fork and local folder (default: workbench)
+  --no-fork                       Clone without forking (read-only)
+  --no-tui                        Skip TUI, use defaults or provided values
+  --org <name>                    GitHub organization name
   --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 (default: main)
@@ -59,13 +76,11 @@ OPTIONS:
   --help                          Display this help message
 
 EXAMPLES:
+  workbench --init
+  workbench --init --no-tui --name my-project
+  workbench --init --no-tui --no-fork --name explore-wb
+  workbench --init --no-tui --name my-project --org myorg --code-repository https://github.com/myorg/api
   workbench --org myorg --code-repository https://github.com/myorg/backend
-
-  workbench --org myorg --code-repository https://github.com/myorg/api \\
-                       --code-repository https://github.com/myorg/web \\
-                       --resource-repository https://github.com/myorg/docs \\
-                       --code-branch develop --index off
-
   workbench --tui
 `)
 }