fix(cli): allow options after project directory (#241)

* fix(cli): allow options after project directory

Typer registered `cache` as a nested command group, so Click treated
tokens after the positional project path as COMMAND names
(`No such command '--template'`). Use a single TyperCommand for scaffold
and keep cache routing in main(). Bump create-awesome-python-app to 0.2.7.

* docs: avoid duplicate CHANGELOG Fixes heading for markdownlint

Author: ulises-jeremias

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.7 - 2026-07-22
+
+### CLI
+
+- Allow options after the project directory (`uvx create-awesome-python-app my-api --template …`). Typer was registering `cache` as a nested command group, so Click treated `--template` as a COMMAND name.
+
 ## 0.2.6 - 2026-07-18
 
 ### Docs

packages/create-awesome-python-app/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "create-awesome-python-app"
-version = "0.2.6"
+version = "0.2.7"
 description = "Composable scaffolding CLI for production-ready Python apps"
 readme = "README.md"
 requires-python = ">=3.12"

packages/create-awesome-python-app/src/create_awesome_python_app/__init__.py

@@ -1,3 +1,3 @@
 """Create Awesome Python App CLI."""
 
-__version__ = "0.2.6"
+__version__ = "0.2.7"

packages/create-awesome-python-app/src/create_awesome_python_app/cli.py

@@ -34,9 +34,12 @@
     help="Composable scaffolding CLI for production-ready Python apps.",
     no_args_is_help=False,
     add_completion=True,
+    # Keep cache out of this Typer app (routed in main()). A nested command
+    # group turns the CLI into Click Group form `[ARGS] COMMAND`, so
+    # `cpa my-api --template …` fails with "No such command '--template'".
+    epilog="Cache: create-awesome-python-app cache [list|dir|clean|verify|…]",
 )
 cache_app = typer.Typer(help="Inspect and manage the local template cache")
-app.add_typer(cache_app, name="cache")
 console = Console(stderr=True)
 
 
@@ -209,9 +212,8 @@ def main() -> None:
     app()
 
 
-@app.callback(invoke_without_command=True)
+@app.command(name="create-awesome-python-app")
 def scaffold(
-    ctx: typer.Context,
     project_directory: str | None = typer.Argument("my-project"),
     version: bool = typer.Option(False, "--version"),
     info: bool = typer.Option(False, "--info", "-i"),
@@ -247,8 +249,6 @@ def scaffold(
         raise typer.Exit(0)
     if info:
         print_env_info()
-    if ctx.invoked_subcommand is not None:
-        return
 
     # Translate --fixture into env vars before catalog loads
     # (--list-templates / interactive / scaffold).

packages/create-awesome-python-app/tests/test_cli.py

@@ -223,6 +223,54 @@ def test_help_mentions_fixture() -> None:
     assert "fixture" in text.lower()
 
 
+def test_options_after_project_directory(tmp_path: Path, monkeypatch) -> None:
+    """Regression: README-style `cpa my-api --template …` must work.
+
+    Registering a Typer subcommand group made Click treat ``--template`` as a
+    COMMAND after the positional project directory.
+    """
+    tpl = tmp_path / "tpl"
+    tpl.mkdir()
+    captured: dict[str, object] = {}
+
+    async def fake_check_for_latest_version(_package_name):
+        return None
+
+    async def fake_create_python_app(project_directory, options, *_args, **_kwargs):
+        captured["project_directory"] = project_directory
+        captured["options"] = options
+
+    monkeypatch.setattr(
+        "create_awesome_python_app.cli.check_for_latest_version",
+        fake_check_for_latest_version,
+    )
+    monkeypatch.setattr(
+        "create_awesome_python_app.cli.create_python_app",
+        fake_create_python_app,
+    )
+
+    result = runner.invoke(
+        app,
+        [
+            "my-api",
+            "--template",
+            f"file://{tpl}",
+            "--addons",
+            "github-setup",
+            "--no-install",
+            "--no-interactive",
+        ],
+    )
+
+    text = (result.stdout or "") + (result.stderr or "")
+    assert result.exit_code == 0, text
+    assert "No such command" not in text
+    assert captured["project_directory"] == "my-api"
+    options = captured["options"]
+    assert isinstance(options, dict)
+    assert options["template"] == f"file://{tpl}"
+
+
 def test_preprocess_fixture_argv_bare_and_with_dir() -> None:
     from create_awesome_python_app.cli import _FIXTURE_AUTO, _preprocess_fixture_argv