Make the CLI robust at its edges

Config saving round-trips any input, the update check understands
pre-releases, non-interactive runs fail safely on a dirty tree, setup and
test regain the scriptability and filtering users had before, and every
command has CLI-level test coverage.

- save_config uses a TOML writer, so quotes and backslashes no longer
  produce a config the tool cannot read back; load errors name the path
- version comparison via PEP 440, so beta users are told about newer betas
- dirty tree aborts in non-interactive mode; --allow-dirty opts back in
- setup takes --data, --data-file and --defaults like create/add
- test -t NAME / -s TARGET pass through to the invoke task and the command
  exits with the test run's exit code
- serve/test/debug explain a missing uv, tasks.py, invoke or pytest
- auto-commit failures go to the styled error channel
- fixes "completion <shell> --install", which the new tests caught

Requires the matching test task in copier-templates; projects with an older
tasks.py get a message naming the fix.

Author: MrTango

CHANGES.md

@@ -3,7 +3,54 @@
 ## 7.0.0b14 (unreleased)
 
 
-- Nothing changed yet.
+- Save `~/.plonecli/config.toml` with a real TOML writer, so quotes, backslashes
+  and newlines in any value round-trip instead of producing a file plonecli can
+  no longer read. An unreadable config now fails with a message naming the path.
+  [MrTango]
+
+- Compare versions with PEP 440 in the update check, so users on a beta are told
+  about newer betas and a final release is never "updated" to an older one.
+  [MrTango]
+
+- Abort instead of proceeding when a template runs on a git repository with
+  uncommitted changes in non-interactive mode (`--defaults` or no terminal). New
+  `--allow-dirty` flag on `create`, `add` and `setup` opts back in.
+  [MrTango]
+
+- Give `setup` the `--data`, `--data-file` and `--defaults` options of
+  `create`/`add`, so a backend addon can be bootstrapped from a script or CI.
+  [MrTango]
+
+- Restore test filtering: `plonecli test -t NAME` runs a single test and
+  `-s TARGET` restricts the run to one package. Both pass through to the
+  generated `invoke test` task; projects with an older `tasks.py` get a message
+  naming the fix instead of an unknown-flag error from invoke.
+  [MrTango]
+
+- `plonecli test` now exits with the test run's exit code, so a failing test run
+  fails the command.
+  [MrTango]
+
+- Report a failed git auto-commit as a coloured error on stderr naming the
+  uncommitted directory, instead of a bare stdout print.
+  [MrTango]
+
+- Explain what is missing when `serve`, `test` or `debug` cannot run the invoke
+  tasks - no `uv` on PATH, no generated `tasks.py`, or a project that does not
+  declare `invoke` (dev group) or `pytest` (`test` extra) - instead of failing
+  inside a subprocess.
+  [MrTango]
+
+- Fix `plonecli completion <shell> --install`, which failed with
+  "No such option: --install" because the chained top-level group disables
+  interspersed arguments.
+  [MrTango]
+
+- Add CLI-level tests for `config`, `update`, `setup` and `completion`, unit
+  tests for the Plone-version fetching module, and update-banner tests. Document
+  the full command set, the non-interactive options and the test filters in the
+  README.
+  [MrTango]
 
 
 ## 7.0.0b13 (2026-07-24)

README.md

@@ -132,21 +132,49 @@ This creates `~/.plonecli/config.toml` with your settings.
 plonecli --help
 
 Commands:
-  add      Add features to your existing Plone package
-  config   Configure plonecli global settings
-  create   Create a new Plone package
-  debug    Start the Plone instance in debug mode
-  serve    Start the Plone instance
-  setup    Run zope-setup inside an existing backend_addon
-  test     Run the tests in your package
-  update   Update copier-templates and check for plonecli updates
+  add         Add features to your existing Plone package
+  completion  Show or install shell completion
+  config      Configure plonecli global settings
+  create      Create a new Plone package
+  debug       Start the Plone instance in debug mode
+  serve       Start the Plone instance
+  setup       Run zope-setup inside an existing backend_addon
+  skill       Install/update the bundled Agent Skills for AI coding agents
+  test        Run the tests in your package
+  update      Update copier-templates and check for plonecli updates
 
 Options:
   -l, --list-templates   List available templates
-  -V, --versions         Show version information
+  -V, --versions         Show plonecli and copier-templates versions
   -h, --help             Show this message and exit.
 ```
 
+The list is context-aware: outside a Plone project only the global commands
+(`completion`, `config`, `create`, `skill`, `update`) are shown; inside one,
+`create` is replaced by the project commands.
+
+`create`, `add` and `setup` share the non-interactive options, so a package can
+be bootstrapped from a script or CI:
+
+```shell
+plonecli create addon collective.todo --defaults -d description="Todo lists"
+plonecli add content_type --defaults --data-file answers.yml
+plonecli setup --defaults -d plone_version=6.1.1
+```
+
+| Option              | What it does                                                       |
+|---------------------|--------------------------------------------------------------------|
+| `-d KEY=VALUE`      | Pre-fill a template answer (repeatable), skipping its prompt        |
+| `--data-file FILE`  | Load answers from a YAML/JSON file (`-d` wins on conflicts)        |
+| `--defaults`        | Use template defaults for unanswered questions instead of prompting |
+| `--allow-dirty`     | Run even if the git repository has uncommitted changes              |
+| `--no-git`          | Skip the auto-commit (`create`, `add`)                              |
+
+On a repository with uncommitted changes, an interactive run asks whether to
+continue, and a non-interactive one (`--defaults`, or no terminal) aborts so
+generated files never silently mix into your work in progress. Pass
+`--allow-dirty` when that mixing is intended.
+
 
 ### Creating a Plone Add-on
 
@@ -205,6 +233,20 @@ With verbose output:
 plonecli test --verbose
 ```
 
+Run a single test, or restrict the run to one package:
+
+```shell
+plonecli test -t test_behavior_installed
+plonecli test -s src/collective/todo
+```
+
+Both are passed to the project's `invoke test` task: `-t/--test` becomes pytest's
+`-k`, and `-s/--package` becomes the pytest target path. `plonecli test` exits
+with the test run's exit code, so it can gate a script or a CI job.
+
+Projects generated before the task gained these parameters need their `tasks.py`
+refreshed with `plonecli update && plonecli setup`.
+
 
 ### Debug Mode
 
@@ -314,6 +356,10 @@ local_path = "~/.copier-templates/plone-copier-templates"
 
 The default Plone version is fetched from `https://dist.plone.org/release/` and cached for 24 hours.
 
+Run `plonecli config` to (re)write the file interactively. If it ever becomes
+unreadable, plonecli says so and names the path — delete it and run
+`plonecli config` again to start fresh.
+
 ### Environment Variables
 
 You can override template configuration using environment variables. These take precedence over the config file: