From 4e049739ef63972b6e499a10fc2f0f9cae221335 Mon Sep 17 00:00:00 2001 From: Austin Gregg-Smith Date: Sat, 17 Jan 2026 17:06:36 +0000 Subject: [PATCH 1/4] docs: Update README to match current CLI syntax The README was using outdated flag-based syntax (--stop, --rm, --code, etc.) while the tool now uses workspace subcommands (dl stop, etc.). Also adds documentation maintenance reminder to AGENTS.md. Co-Authored-By: Claude Opus 4.5 --- AGENTS.md | 4 ++++ README.md | 43 +++++++++++++++++++++++++++---------------- 2 files changed, 31 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b9c826c9..52592ab7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,3 +15,7 @@ When using pixi tasks, prefer `pixi run `. See `pixi task list` for availa For tools installed as dependencies (like `gh`), you can run them via: - `pixi run gh ` - works in any shell - `gh ` - works in login shells (`bash -l -c '...'`) + +## Documentation Maintenance + +- **Keep README up to date**: When modifying CLI commands, flags, or usage patterns, update the README.md to reflect the current tool behavior. Run `pixi run dl --help` to see the current help output and ensure the README matches. diff --git a/README.md b/README.md index af55535c..73be0f9b 100644 --- a/README.md +++ b/README.md @@ -33,27 +33,35 @@ source ~/.bashrc # or restart your terminal ## Usage ```bash -dl # Interactive workspace selector (fzf) -dl # Start workspace and attach shell -dl # Run command in workspace -dl owner/repo # Create workspace from GitHub repo -dl owner/repo@branch # Create workspace from specific branch -dl ./path # Create workspace from local path +dl # Interactive workspace selector (fzf) +dl # Start workspace and attach shell +dl # Run workspace command (stop, code, etc.) +dl -- # Run shell command in workspace +dl owner/repo # Create workspace from GitHub repo +dl owner/repo@branch # Create workspace from specific branch +dl ./path # Create workspace from local path ``` -## Commands +## Workspace Commands + +| Command | Description | +|---------|-------------| +| `dl stop` | Stop the workspace | +| `dl rm` | Delete the workspace (alias: `prune`) | +| `dl code` | Open workspace in VS Code | +| `dl restart` | Stop and start (no rebuild) | +| `dl recreate` | Recreate container | +| `dl reset` | Reset workspace (clean slate) | +| `dl -- ` | Run shell command in workspace | + +## Global Commands | Command | Description | |---------|-------------| | `dl --ls` | List all workspaces | -| `dl --stop ` | Stop a workspace | -| `dl --rm ` | Delete a workspace | -| `dl --code ` | Open workspace in VS Code | -| `dl --status ` | Show workspace status | -| `dl --recreate ` | Recreate workspace container | -| `dl --reset ` | Reset workspace (clean slate) | | `dl --install` | Install shell completions | -| `dl --help` | Show help | +| `dl --help, -h` | Show help | +| `dl --version` | Show version | ## Examples @@ -74,10 +82,13 @@ dl blooop/devlaunch@main dl ./my-project # Open workspace in VS Code -dl --code myproject +dl blooop/devlaunch code # Run a command in workspace -dl myproject 'make test' +dl blooop/devlaunch -- make test + +# Stop a workspace +dl blooop/devlaunch stop ``` ## Features From 4fe5cce685c7592b99fc638296ad9f036440fb9d Mon Sep 17 00:00:00 2001 From: Austin Gregg-Smith Date: Sat, 17 Jan 2026 17:07:31 +0000 Subject: [PATCH 2/4] update pixi.lock --- pixi.lock | 4 ++-- pyproject.toml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/pixi.lock b/pixi.lock index e4eab6d1..5a917a12 100644 --- a/pixi.lock +++ b/pixi.lock @@ -382,8 +382,8 @@ packages: requires_python: '>=3.10' - pypi: ./ name: devlaunch - version: 0.0.2 - sha256: 93ade45ee736ac6d8740aad89fdf34015b108de4c3e8bba8f6bc186cfc770af3 + version: 0.0.3 + sha256: f4cd1f0acf28be94078eade0b25d7510e4d0c0e7c4298aa2cd9aa133c63275e6 requires_dist: - iterfzf>=1.0.0 - pylint>=3.2.5,<=4.0.4 ; extra == 'test' diff --git a/pyproject.toml b/pyproject.toml index 914b81db..0c1ed1d2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "devlaunch" -version = "0.0.2" +version = "0.0.3" authors = [{ name = "Austin Gregg-Smith", email = "blooop@gmail.com" }] description = "DevLaunch - A streamlined CLI for devpod workspaces" readme = "README.md" From d3da1b9cf98619ed5ccc390e54ab1edf28ea4e1e Mon Sep 17 00:00:00 2001 From: Austin Gregg-Smith Date: Sat, 17 Jan 2026 17:08:44 +0000 Subject: [PATCH 3/4] docs: Address PR feedback on README examples - Standardize examples to use consistent naming (`myworkspace`, `user/repo`) - Add explicit `prune` entry to workspace commands table - Fix outdated `--stop` reference in Shell Completion section Co-Authored-By: Claude Opus 4.5 --- README.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 73be0f9b..75f994a0 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,8 @@ dl ./path # Create workspace from local path | Command | Description | |---------|-------------| | `dl stop` | Stop the workspace | -| `dl rm` | Delete the workspace (alias: `prune`) | +| `dl rm` | Delete the workspace | +| `dl prune` | Delete the workspace (alias for `rm`) | | `dl code` | Open workspace in VS Code | | `dl restart` | Stop and start (no rebuild) | | `dl recreate` | Recreate container | @@ -69,26 +70,25 @@ dl ./path # Create workspace from local path # Select workspace interactively with fzf dl -# Open an existing workspace -dl myproject +# Open an existing workspace by name +dl myworkspace # Create workspace from GitHub repository -dl loft-sh/devpod +dl user/repo # Create workspace from specific branch -dl blooop/devlaunch@main +dl user/repo@main # Create workspace from local folder dl ./my-project -# Open workspace in VS Code -dl blooop/devlaunch code +# Workspace commands (stop, code, rm, prune, restart, recreate, reset) +dl myworkspace stop +dl myworkspace code +dl myworkspace prune -# Run a command in workspace -dl blooop/devlaunch -- make test - -# Stop a workspace -dl blooop/devlaunch stop +# Run a shell command in workspace +dl myworkspace -- make test ``` ## Features @@ -106,7 +106,7 @@ After running `dl --install`, you get intelligent tab completion: - Workspace names from your devpod list - Known GitHub owners and repositories from your workspaces - File/directory paths when starting with `./`, `/`, or `~` -- All command flags (`--ls`, `--stop`, etc.) +- All global flags (`--ls`, `--install`, etc.) and workspace commands ## Development From 1b95c59ae9e788eae394a5d3439023f0f63ca341 Mon Sep 17 00:00:00 2001 From: Austin Gregg-Smith Date: Sat, 17 Jan 2026 17:10:33 +0000 Subject: [PATCH 4/4] docs: Align README with --help output - Use pattern instead of - Add Workspace Sources section matching help - Use concrete examples (devpod, loft-sh/devpod, blooop/devlaunch) - Match help descriptions exactly Co-Authored-By: Claude Opus 4.5 --- README.md | 65 ++++++++++++++++++++++++------------------------------- 1 file changed, 28 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 75f994a0..ca072b04 100644 --- a/README.md +++ b/README.md @@ -34,26 +34,31 @@ source ~/.bashrc # or restart your terminal ```bash dl # Interactive workspace selector (fzf) -dl # Start workspace and attach shell -dl # Run workspace command (stop, code, etc.) -dl -- # Run shell command in workspace -dl owner/repo # Create workspace from GitHub repo -dl owner/repo@branch # Create workspace from specific branch -dl ./path # Create workspace from local path +dl # Start workspace and attach shell +dl # Run workspace command (stop, code, etc.) +dl -- # Run shell command in workspace +``` + +## Workspace Sources + +```bash +dl myproject # Existing workspace by name +dl user/repo # Create from GitHub repo +dl user/repo@branch # Create from specific branch +dl ./path # Create from local path ``` ## Workspace Commands | Command | Description | |---------|-------------| -| `dl stop` | Stop the workspace | -| `dl rm` | Delete the workspace | -| `dl prune` | Delete the workspace (alias for `rm`) | -| `dl code` | Open workspace in VS Code | -| `dl restart` | Stop and start (no rebuild) | -| `dl recreate` | Recreate container | -| `dl reset` | Reset workspace (clean slate) | -| `dl -- ` | Run shell command in workspace | +| `dl stop` | Stop the workspace | +| `dl rm, prune` | Delete the workspace | +| `dl code` | Open in VS Code | +| `dl restart` | Stop and start (no rebuild) | +| `dl recreate` | Recreate container | +| `dl reset` | Clean slate (remove all, recreate) | +| `dl -- ` | Run shell command in workspace | ## Global Commands @@ -61,34 +66,20 @@ dl ./path # Create workspace from local path |---------|-------------| | `dl --ls` | List all workspaces | | `dl --install` | Install shell completions | -| `dl --help, -h` | Show help | +| `dl --help, -h` | Show this help | | `dl --version` | Show version | ## Examples ```bash -# Select workspace interactively with fzf -dl - -# Open an existing workspace by name -dl myworkspace - -# Create workspace from GitHub repository -dl user/repo - -# Create workspace from specific branch -dl user/repo@main - -# Create workspace from local folder -dl ./my-project - -# Workspace commands (stop, code, rm, prune, restart, recreate, reset) -dl myworkspace stop -dl myworkspace code -dl myworkspace prune - -# Run a shell command in workspace -dl myworkspace -- make test +dl # Select workspace with fzf +dl devpod # Open existing workspace +dl loft-sh/devpod # Create from GitHub +dl blooop/devlaunch@main # Create from specific branch +dl ./my-project # Create from local folder +dl blooop/devlaunch code # Open in VS Code +dl blooop/devlaunch -- make test # Run command in workspace +dl blooop/devlaunch stop # Stop workspace ``` ## Features