Streamline / modernize commands (#472)

Modernize CLI with DevOps conventions

why: The previous CLI lacked modern DevOps tooling conventions, making it harder
to preview changes, introspect configuration, and integrate with CI/CD pipelines.
Users had no way to list repos or check status without syncing, and the import
command tried to do two unrelated things (add single repo vs scan filesystem).

what:
- BREAKING: Remove vcspull import command, split into add and discover
- BREAKING: Rename -c/--config → -f/--file across all commands
- NEW: vcspull list - List configured repositories with --tree, --json, --ndjson
- NEW: vcspull status - Check repository health (clean/dirty, ahead/behind)
- NEW: vcspull add - Add single repository to configuration
- NEW: vcspull discover - Scan filesystem for existing repositories
- NEW: --dry-run/-n for sync, add, discover commands
- NEW: --json/--ndjson structured output for automation
- NEW: -w short flag for --workspace-root (all 3 aliases supported)
- NEW: --color {auto,always,never} with NO_COLOR support
- NEW: Terraform-style dry-run plans for vcspull sync
- NEW: Async progress tracking for sync planning on TTYs
- Add comprehensive test coverage: 46 new tests (1,803 lines)
- Add complete documentation for all new commands
- Add semantic colors infrastructure (_colors.py)
- Add output formatting infrastructure (_output.py)
- Add workspace filtering helper (_workspaces.py)

Migration guide:
  vcspull import NAME URL       → vcspull add NAME URL
  vcspull import --scan DIR     → vcspull discover DIR
  vcspull sync -c FILE          → vcspull sync -f FILE
  vcspull sync --workspace-root → vcspull sync -w PATH

Benefits:
- Better DX: Commands are clearer and more intuitive
- Safer: Dry-run mode prevents mistakes
- More discoverable: List and status commands for introspection
- Familiar: Matches patterns from Terraform, Cargo, Ruff, Biome
- CI/CD friendly: JSON/NDJSON output for scripting
- Type-safe: Full mypy coverage on all new code

Stats: 45 files changed, 6412 insertions(+), 1375 deletions(-)
Tests: 192/192 passing (146 original + 46 new)

refs: Aligns with modern DevOps CLI conventions

Author: tony

CHANGES

@@ -31,7 +31,57 @@ $ pipx install --suffix=@next 'vcspull' --pip-args '\--pre' --force
 
 <!-- Maintainers, insert changes / features for the next release here -->
 
-_Notes on upcoming releases will be added here_
+### Breaking Changes
+
+This release modernizes the vcspull CLI to align with DevOps tool conventions (Terraform, Cargo, Ruff, Biome). **This is a breaking change release**.
+
+#### Command Changes (#472)
+
+- **REMOVED**: `vcspull import` command
+  - Replaced by `vcspull add <name> <url>` to add a single repository
+  - Replaced by `vcspull discover <path>` to scan and add multiple repositories
+- **NEW**: `vcspull list` - List configured repositories with optional `--tree`, `--json`, `--ndjson` output
+- **NEW**: `vcspull status` - Check repository health (clean/dirty status, ahead/behind tracking with `--detailed`)
+
+#### Flag Changes (#472)
+
+- **RENAMED**: `-c/--config` → `-f/--file` (all commands)
+- **NEW**: `-w/--workspace/--workspace-root` - All three aliases supported for workspace root
+- **NEW**: `--dry-run/-n` - Preview changes without making modifications (sync, add, discover)
+- **NEW**: `--json/--ndjson` - Machine-readable output for automation (sync, list, status)
+- **NEW**: `--color {auto,always,never}` - Control color output
+
+#### Migration Guide (#472)
+
+```bash
+# Old → New
+vcspull import NAME URL              → vcspull add NAME URL
+vcspull import --scan DIR            → vcspull discover DIR
+vcspull sync -c FILE                 → vcspull sync -f FILE
+vcspull sync --workspace-root PATH   → vcspull sync -w PATH  # (or keep long form)
+vcspull fmt -c FILE                  → vcspull fmt -f FILE
+```
+
+### Features
+
+#### Developer Experience Improvements (#472)
+
+- Action commands (`sync`, `add`, `discover`) support `--dry-run` for safe previewing of changes
+- Structured output (`--json`, `--ndjson`) enables CI/CD integration and automation
+- Semantic colors with `NO_COLOR` environment variable support
+- Short `-w` flag for workspace root reduces typing
+- Consistent flag naming across all commands
+- `vcspull sync --dry-run` renders a Terraform-style plan (with live progress on
+  TTYs) and exposes the same data via a stable JSON/NDJSON schema for automation
+
+#### New Introspection Commands (#472)
+
+- `vcspull list` - View all configured repositories
+  - `--tree` mode groups by workspace root
+  - `--json/--ndjson` for programmatic access
+- `vcspull status` - Check repository health
+  - Shows which repos exist, are clean/dirty, or missing
+  - `--detailed` mode shows branch, ahead/behind tracking, and full paths
 
 ## vcspull v1.38.0 (2025-10-18)
 

README.md

@@ -68,7 +68,7 @@ You can test the unpublished version of vcspull before its released.
 ## Configuration
 
 Add your repos to `~/.vcspull.yaml`. You can edit the file by hand or let
-`vcspull import` create entries for you.
+`vcspull add` or `vcspull discover` create entries for you.
 
 ```yaml
 ~/code/:
@@ -91,40 +91,68 @@ more [configuration](https://vcspull.git-pull.com/configuration.html))
 be used as a declarative manifest to clone your repos consistently across
 machines. Subsequent syncs of initialized repos will fetch the latest commits.
 
-### Import repositories from the CLI
+### Add repositories from the CLI
 
-Register an existing remote without touching YAML manually:
+Register a single repository without touching YAML manually:
 
 ```console
-$ vcspull import my-lib https://github.com/example/my-lib.git --path ~/code/my-lib
+$ vcspull add my-lib https://github.com/example/my-lib.git --path ~/code/my-lib
 ```
 
 - Omit `--path` to default the entry under `./`.
-- Use `--workspace-root` when you want to force a specific workspace root, e.g.
-  `--workspace-root ~/projects/libs`.
-- Pass `-c/--config` to import into an alternate YAML file.
+- Use `-w/--workspace` when you want to force a specific workspace root, e.g.
+  `-w ~/projects/libs`.
+- Pass `-f/--file` to add to an alternate YAML file.
+- Use `--dry-run` to preview changes before writing.
 - Follow with `vcspull sync my-lib` to clone or update the working tree after registration.
 
-### Scan local checkouts and import en masse
+### Discover local checkouts and add en masse
 
 Have a directory tree full of cloned Git repositories? Scan and append them to
 your configuration:
 
 ```console
-$ vcspull import --scan ~/code --recursive
+$ vcspull discover ~/code --recursive
 ```
 
 The scan shows each repository before import unless you opt into `--yes`. Add
-`--workspace-root ~/code/` to pin the resulting workspace root or `--config` to
+`-w ~/code/` to pin the resulting workspace root or `-f` to
 write somewhere other than the default `~/.vcspull.yaml`.
 
+### Inspect configured repositories
+
+List what vcspull already knows about without mutating anything:
+
+```console
+$ vcspull list
+$ vcspull list --tree
+$ vcspull list --json | jq '.[].name'
+```
+
+`--json` emits a single JSON array, while `--ndjson` streams newline-delimited
+objects that are easy to consume from shell pipelines.
+
+### Check repository status
+
+Get a quick health check for all configured workspaces:
+
+```console
+$ vcspull status
+$ vcspull status --detailed
+$ vcspull status --ndjson | jq --slurp 'map(select(.reason == "summary"))'
+```
+
+The status command respects `--workspace/-w` filters and the global
+`--color {auto,always,never}` flag. JSON and NDJSON output mirrors the list
+command for automation workflows.
+
 ### Normalize configuration files
 
 After importing or editing by hand, run the formatter to tidy up keys and keep
 entries sorted:
 
 ```console
-$ vcspull fmt --config ~/.vcspull.yaml --write
+$ vcspull fmt -f ~/.vcspull.yaml --write
 ```
 
 Use `vcspull fmt --all --write` to format every YAML file that vcspull can
@@ -136,6 +164,21 @@ discover under the standard config locations.
 $ vcspull sync
 ```
 
+Preview planned work with Terraform-style plan output or emit structured data
+for CI/CD:
+
+```console
+$ vcspull sync --dry-run "*"
+$ vcspull sync --dry-run --show-unchanged "workspace-*"
+$ vcspull sync --dry-run --json "*" | jq '.summary'
+$ vcspull sync --dry-run --ndjson "*" | jq --slurp 'map(select(.type == "summary"))'
+```
+
+Dry runs stream a progress line when stdout is a TTY, then print a concise plan
+summary (`+/~/✓/⚠/✗`) grouped by workspace. Use `--summary-only`,
+`--relative-paths`, `--long`, or `-v/-vv` for alternate views, and
+`--fetch`/`--offline` to control how remote metadata is refreshed.
+
 Keep nested VCS repositories updated too, lets say you have a mercurial
 or svn project with a git dependency:
 
@@ -149,7 +192,7 @@ or svn project with a git dependency:
 Clone / update repos via config file:
 
 ```console
-$ vcspull sync -c external_deps.yaml '*'
+$ vcspull sync -f external_deps.yaml '*'
 ```
 
 See the [Quickstart](https://vcspull.git-pull.com/quickstart.html) for

docs/Makefile

@@ -6,9 +6,14 @@ WATCH_FILES= find .. -type f -not -path '*/\.*' | grep -i '.*[.]\(rst\|md\)\$\|.
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+# Keep ANSI color codes out of generated docs (Sphinx + argparse) by forcing
+# Python's colour support off for every build command.
+SPHINX_ENV    = PYTHON_COLORS=0 NO_COLOR=1
+SPHINXBUILD   = $(SPHINX_ENV) sphinx-build
 PAPER         =
 BUILDDIR      = _build
+# Apply the same environment when running the live-reload server.
+SPHINX_AUTOBUILD = $(SPHINX_ENV) uv run sphinx-autobuild
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -182,8 +187,8 @@ dev:
 	$(MAKE) -j watch serve
 
 start:
-	uv run sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) --port ${HTTP_PORT} $(O)
+	$(SPHINX_AUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) --port ${HTTP_PORT} $(O)
 
 design:
 	# This adds additional watch directories (for _static file changes) and disable incremental builds
-	uv run sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) --port ${HTTP_PORT} --watch "." -a $(O)
+	$(SPHINX_AUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) --port ${HTTP_PORT} --watch "." -a $(O)

docs/api/cli/add.md

@@ -0,0 +1,8 @@
+# vcspull add - `vcspull.cli.add`
+
+```{eval-rst}
+.. automodule:: vcspull.cli.add
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```

docs/api/cli/discover.md

@@ -0,0 +1,8 @@
+# vcspull discover - `vcspull.cli.discover`
+
+```{eval-rst}
+.. automodule:: vcspull.cli.discover
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```

docs/api/cli/import.md

@@ -1,8 +1,16 @@
 # vcspull import - `vcspull.cli._import`
 
-```{eval-rst}
-.. automodule:: vcspull.cli._import
-   :members:
-   :show-inheritance:
-   :undoc-members:
+```{warning}
+**This module has been removed** as of vcspull 1.38.0.
+
+The `vcspull.cli._import` module has been split into two separate modules:
+- {py:mod}`vcspull.cli.add` - Add single repositories manually
+- {py:mod}`vcspull.cli.discover` - Scan directories for existing repositories
+
+See the user-facing documentation at {ref}`cli-add` and {ref}`cli-discover`.
 ```
+
+## Historical API Reference
+
+This module previously provided the `import` command functionality but has been
+replaced with more focused commands.

docs/api/cli/index.md

@@ -9,7 +9,10 @@
 :maxdepth: 1
 
 sync
-import
+add
+discover
+list
+status
 fmt
 ```
 

docs/api/cli/list.md

@@ -0,0 +1,8 @@
+# vcspull list - `vcspull.cli.list`
+
+```{eval-rst}
+.. automodule:: vcspull.cli.list
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```

docs/api/cli/status.md

@@ -0,0 +1,8 @@
+# vcspull status - `vcspull.cli.status`
+
+```{eval-rst}
+.. automodule:: vcspull.cli.status
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```