avalon-cli 0.2.0__tar.gz

avalon_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nehz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

avalon_cli-0.2.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: avalon-cli
+Version: 0.2.0
+Summary: Command-line companion for the Avalon real-time web framework: scaffold projects and run an auto-reloading dev server.
+Author: nehz
+License-Expression: MIT
+Keywords: avalon,cli,scaffold,dev-server,real-time,web
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# avalon-cli
+
+**The command-line companion for the [Avalon](https://pypi.org/project/avalon/) real-time web framework.**
+
+`avalon-cli` gets you from zero to a running, auto-reloading app in two commands:
+`avalon new` scaffolds a project and `avalon dev` runs it, restarting the server
+every time you save a file. It uses only the Python standard library and does not
+import `avalon` itself, so it installs in seconds and works with any Avalon version
+(or with no framework at all, via the `static` template).
+
+## Features
+
+- **Project scaffolding**: `avalon new` generates a ready-to-run project from a built-in template.
+- **Auto-reloading dev server**: `avalon dev` runs your dev command, watches files by polling
+  (no native dependencies), and restarts the process on change. If the process crashes it waits
+  for your fix and starts again on the next save, so you never have to restart `avalon dev`.
+- **One config file**: `avalon.toml` holds the dev command, host, port and watch rules, found by
+  walking upward from the current directory.
+- **Clean shutdown**: Ctrl-C or SIGTERM always terminates the child process; nothing is orphaned.
+- **Zero dependencies**: standard library only, Python 3.11+.
+
+## Install
+
+```bash
+pip install avalon-cli
+```
+
+This installs the `avalon` command. `python -m avalon_cli` works too.
+
+## Quickstart
+
+```bash
+avalon new chat-demo            # Avalon app (default "minimal" template)
+cd chat-demo
+pip install avalon              # the framework the generated app.py uses
+avalon dev                      # http://127.0.0.1:8000/, reloads on save
+```
+
+No framework yet? The `static` template needs nothing but Python:
+
+```bash
+avalon new mysite --template static
+avalon dev -C mysite --port 9000
+```
+
+## Commands
+
+All commands print errors as `error: <message>` on stderr and exit with status 1;
+usage errors exit with status 2.
+
+### `avalon new NAME [-t TEMPLATE] [-d DIRECTORY] [--force]`
+
+Create the directory `DIRECTORY/NAME` and fill it from a template.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `NAME` | (required) | Project name and directory name. Must start with a letter and contain only letters, digits, `-` and `_`. |
+| `-t`, `--template` | `minimal` | One of the templates listed by `avalon templates`. |
+| `-d`, `--directory` | `.` | Parent directory to create the project in. |
+| `--force` | off | Write into an existing non-empty directory, overwriting files the template provides (other files are left alone). |
+
+An existing *empty* directory is always accepted.
+
+### `avalon templates`
+
+List the built-in templates:
+
+| Template | Files | Notes |
+| --- | --- | --- |
+| `minimal` (default) | `avalon.toml`, `app.py`, `templates/index.html`, `README.md`, `.gitignore` | An Avalon app with one page and a WebSocket echo endpoint. Requires `avalon`. |
+| `static` | `avalon.toml`, `public/index.html`, `public/style.css`, `public/app.js`, `README.md`, `.gitignore` | Served by `python -m http.server`; no dependencies. |
+
+### `avalon dev [-C PROJECT] [--host HOST] [-p PORT] [--interval SECONDS] [--no-reload]`
+
+Find `avalon.toml` (in `PROJECT` or any parent directory), start the configured dev
+command from the project root, and restart it whenever a watched file is added,
+modified or removed.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `-C`, `--project` | `.` | Directory to start looking for `avalon.toml`. |
+| `--host` | `[dev].host` | Overrides the host. |
+| `-p`, `--port` | `[dev].port` | Overrides the port (1-65535). |
+| `--interval` | `[dev].interval` | Seconds between file-change polls. |
+| `--no-reload` | off | Run the command once, without watching; `avalon dev` exits with the command's exit code. |
+
+The child process receives `AVALON_HOST`, `AVALON_PORT` and `AVALON_ENV=development`
+in its environment. With reloading on, `avalon dev` exits with status 0 on SIGTERM
+and 130 on Ctrl-C.
+
+### `avalon info [-C PROJECT]`
+
+Print the `avalon-cli` and Python versions and, if a project is found, its name,
+root, fully-resolved dev command, address, watch paths and extensions.
+
+### `avalon --version`
+
+Print `avalon 0.2.0`.
+
+## Configuration: `avalon.toml`
+
+```toml
+[project]
+name = "chat-demo"          # default: the directory name
+
+[dev]
+command = "{python} app.py" # placeholders: {host}, {port}, {python}
+host = "127.0.0.1"
+port = 8000
+watch = ["."]               # files or directories, relative to the project root
+extensions = [".py", ".html", ".css", ".js", ".toml"]  # [] watches every file
+ignore = [".venv", ".git", "__pycache__", "node_modules"]  # glob patterns matched against names
+interval = 0.5              # seconds between polls
+```
+
+Every key is optional; the values above are the defaults. Extensions without a
+leading dot get one (`"py"` becomes `".py"`). Unknown keys in `[dev]` are rejected
+so typos are caught early. The command is split shell-style *before* placeholders
+are substituted, so a `{python}` path containing spaces stays a single argument.
+`{python}` is the interpreter running `avalon-cli`.
+
+## Python API
+
+Everything the CLI does is available from `avalon_cli`:
+
+```python
+from avalon_cli import DevServer, build_command, create_project, load_config
+
+result = create_project("chat-demo", template="minimal", parent=".", force=False)
+print(result.root, result.template, result.files)   # ScaffoldResult
+
+config = load_config(result.root)                   # ProjectConfig(root, name, dev=DevConfig(...))
+argv = build_command(config.dev.command, host=config.dev.host, port=config.dev.port)
+
+server = DevServer(
+    argv,
+    cwd=config.root,
+    watch=config.dev.watch,
+    extensions=config.dev.extensions,
+    ignore=config.dev.ignore,
+    interval=config.dev.interval,
+)
+server.run()   # blocks; pass a threading.Event to stop it from another thread
+```
+
+| Name | Description |
+| --- | --- |
+| `create_project(name, template="minimal", parent=".", *, force=False) -> ScaffoldResult` | Scaffold a project; raises `ScaffoldError`. |
+| `load_config(start=".") -> ProjectConfig` | Locate and validate `avalon.toml`; raises `ConfigError`. |
+| `find_project_root(start=".") -> Path` | Directory containing the nearest `avalon.toml`; raises `ConfigError`. |
+| `build_command(template, *, host, port, python=None) -> list[str]` | Turn a dev command template into argv; raises `ValueError`. |
+| `DevServer(argv, *, cwd=".", env=None, watch=(".",), extensions=(), ignore=(), interval=0.5, reload=True, log=...)` | Reloading process runner with `start()`, `stop(timeout=5.0)`, `restart()`, `poll_changes()`, `run(stop_event=None) -> int`, and a `restarts` counter. |
+| `take_snapshot(roots, extensions=(), ignore=()) -> dict[Path, int]` | File-to-mtime map of watched files. |
+| `diff_snapshots(old, new) -> set[Path]` | Paths added, removed or modified between two snapshots. |
+| `TEMPLATES`, `get_template(name)`, `ProjectTemplate` | The built-in template registry. |
+
+## Development
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e .
+python -m unittest discover -s tests -t .
+```
+
+## License
+
+MIT

avalon_cli-0.2.0/README.md

@@ -0,0 +1,167 @@
+# avalon-cli
+
+**The command-line companion for the [Avalon](https://pypi.org/project/avalon/) real-time web framework.**
+
+`avalon-cli` gets you from zero to a running, auto-reloading app in two commands:
+`avalon new` scaffolds a project and `avalon dev` runs it, restarting the server
+every time you save a file. It uses only the Python standard library and does not
+import `avalon` itself, so it installs in seconds and works with any Avalon version
+(or with no framework at all, via the `static` template).
+
+## Features
+
+- **Project scaffolding**: `avalon new` generates a ready-to-run project from a built-in template.
+- **Auto-reloading dev server**: `avalon dev` runs your dev command, watches files by polling
+  (no native dependencies), and restarts the process on change. If the process crashes it waits
+  for your fix and starts again on the next save, so you never have to restart `avalon dev`.
+- **One config file**: `avalon.toml` holds the dev command, host, port and watch rules, found by
+  walking upward from the current directory.
+- **Clean shutdown**: Ctrl-C or SIGTERM always terminates the child process; nothing is orphaned.
+- **Zero dependencies**: standard library only, Python 3.11+.
+
+## Install
+
+```bash
+pip install avalon-cli
+```
+
+This installs the `avalon` command. `python -m avalon_cli` works too.
+
+## Quickstart
+
+```bash
+avalon new chat-demo            # Avalon app (default "minimal" template)
+cd chat-demo
+pip install avalon              # the framework the generated app.py uses
+avalon dev                      # http://127.0.0.1:8000/, reloads on save
+```
+
+No framework yet? The `static` template needs nothing but Python:
+
+```bash
+avalon new mysite --template static
+avalon dev -C mysite --port 9000
+```
+
+## Commands
+
+All commands print errors as `error: <message>` on stderr and exit with status 1;
+usage errors exit with status 2.
+
+### `avalon new NAME [-t TEMPLATE] [-d DIRECTORY] [--force]`
+
+Create the directory `DIRECTORY/NAME` and fill it from a template.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `NAME` | (required) | Project name and directory name. Must start with a letter and contain only letters, digits, `-` and `_`. |
+| `-t`, `--template` | `minimal` | One of the templates listed by `avalon templates`. |
+| `-d`, `--directory` | `.` | Parent directory to create the project in. |
+| `--force` | off | Write into an existing non-empty directory, overwriting files the template provides (other files are left alone). |
+
+An existing *empty* directory is always accepted.
+
+### `avalon templates`
+
+List the built-in templates:
+
+| Template | Files | Notes |
+| --- | --- | --- |
+| `minimal` (default) | `avalon.toml`, `app.py`, `templates/index.html`, `README.md`, `.gitignore` | An Avalon app with one page and a WebSocket echo endpoint. Requires `avalon`. |
+| `static` | `avalon.toml`, `public/index.html`, `public/style.css`, `public/app.js`, `README.md`, `.gitignore` | Served by `python -m http.server`; no dependencies. |
+
+### `avalon dev [-C PROJECT] [--host HOST] [-p PORT] [--interval SECONDS] [--no-reload]`
+
+Find `avalon.toml` (in `PROJECT` or any parent directory), start the configured dev
+command from the project root, and restart it whenever a watched file is added,
+modified or removed.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `-C`, `--project` | `.` | Directory to start looking for `avalon.toml`. |
+| `--host` | `[dev].host` | Overrides the host. |
+| `-p`, `--port` | `[dev].port` | Overrides the port (1-65535). |
+| `--interval` | `[dev].interval` | Seconds between file-change polls. |
+| `--no-reload` | off | Run the command once, without watching; `avalon dev` exits with the command's exit code. |
+
+The child process receives `AVALON_HOST`, `AVALON_PORT` and `AVALON_ENV=development`
+in its environment. With reloading on, `avalon dev` exits with status 0 on SIGTERM
+and 130 on Ctrl-C.
+
+### `avalon info [-C PROJECT]`
+
+Print the `avalon-cli` and Python versions and, if a project is found, its name,
+root, fully-resolved dev command, address, watch paths and extensions.
+
+### `avalon --version`
+
+Print `avalon 0.2.0`.
+
+## Configuration: `avalon.toml`
+
+```toml
+[project]
+name = "chat-demo"          # default: the directory name
+
+[dev]
+command = "{python} app.py" # placeholders: {host}, {port}, {python}
+host = "127.0.0.1"
+port = 8000
+watch = ["."]               # files or directories, relative to the project root
+extensions = [".py", ".html", ".css", ".js", ".toml"]  # [] watches every file
+ignore = [".venv", ".git", "__pycache__", "node_modules"]  # glob patterns matched against names
+interval = 0.5              # seconds between polls
+```
+
+Every key is optional; the values above are the defaults. Extensions without a
+leading dot get one (`"py"` becomes `".py"`). Unknown keys in `[dev]` are rejected
+so typos are caught early. The command is split shell-style *before* placeholders
+are substituted, so a `{python}` path containing spaces stays a single argument.
+`{python}` is the interpreter running `avalon-cli`.
+
+## Python API
+
+Everything the CLI does is available from `avalon_cli`:
+
+```python
+from avalon_cli import DevServer, build_command, create_project, load_config
+
+result = create_project("chat-demo", template="minimal", parent=".", force=False)
+print(result.root, result.template, result.files)   # ScaffoldResult
+
+config = load_config(result.root)                   # ProjectConfig(root, name, dev=DevConfig(...))
+argv = build_command(config.dev.command, host=config.dev.host, port=config.dev.port)
+
+server = DevServer(
+    argv,
+    cwd=config.root,
+    watch=config.dev.watch,
+    extensions=config.dev.extensions,
+    ignore=config.dev.ignore,
+    interval=config.dev.interval,
+)
+server.run()   # blocks; pass a threading.Event to stop it from another thread
+```
+
+| Name | Description |
+| --- | --- |
+| `create_project(name, template="minimal", parent=".", *, force=False) -> ScaffoldResult` | Scaffold a project; raises `ScaffoldError`. |
+| `load_config(start=".") -> ProjectConfig` | Locate and validate `avalon.toml`; raises `ConfigError`. |
+| `find_project_root(start=".") -> Path` | Directory containing the nearest `avalon.toml`; raises `ConfigError`. |
+| `build_command(template, *, host, port, python=None) -> list[str]` | Turn a dev command template into argv; raises `ValueError`. |
+| `DevServer(argv, *, cwd=".", env=None, watch=(".",), extensions=(), ignore=(), interval=0.5, reload=True, log=...)` | Reloading process runner with `start()`, `stop(timeout=5.0)`, `restart()`, `poll_changes()`, `run(stop_event=None) -> int`, and a `restarts` counter. |
+| `take_snapshot(roots, extensions=(), ignore=()) -> dict[Path, int]` | File-to-mtime map of watched files. |
+| `diff_snapshots(old, new) -> set[Path]` | Paths added, removed or modified between two snapshots. |
+| `TEMPLATES`, `get_template(name)`, `ProjectTemplate` | The built-in template registry. |
+
+## Development
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e .
+python -m unittest discover -s tests -t .
+```
+
+## License
+
+MIT

avalon_cli-0.2.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "avalon-cli"
+version = "0.2.0"
+description = "Command-line companion for the Avalon real-time web framework: scaffold projects and run an auto-reloading dev server."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "nehz" }]
+keywords = ["avalon", "cli", "scaffold", "dev-server", "real-time", "web"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Software Development :: Code Generators",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.scripts]
+avalon = "avalon_cli.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+avalon_cli = ["py.typed"]

avalon_cli-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

avalon_cli-0.2.0/src/avalon_cli/__init__.py

@@ -0,0 +1,37 @@
+"""avalon-cli: command-line companion for the Avalon real-time web framework.
+
+The package is self-contained (standard library only) and does not import
+``avalon`` itself. The public API mirrors the CLI commands:
+
+* :func:`create_project` - ``avalon new``
+* :class:`DevServer` / :func:`build_command` - ``avalon dev``
+* :func:`load_config` - reads ``avalon.toml``
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+from .config import ConfigError, DevConfig, ProjectConfig, find_project_root, load_config  # noqa: E402
+from .reloader import DevServer, build_command, diff_snapshots, take_snapshot  # noqa: E402
+from .scaffold import ScaffoldError, ScaffoldResult, create_project  # noqa: E402
+from .templates import TEMPLATES, ProjectTemplate, get_template  # noqa: E402
+
+__all__ = [
+    "__version__",
+    "ConfigError",
+    "DevConfig",
+    "DevServer",
+    "ProjectConfig",
+    "ProjectTemplate",
+    "ScaffoldError",
+    "ScaffoldResult",
+    "TEMPLATES",
+    "build_command",
+    "create_project",
+    "diff_snapshots",
+    "find_project_root",
+    "get_template",
+    "load_config",
+    "take_snapshot",
+]

avalon_cli-0.2.0/src/avalon_cli/__main__.py

@@ -0,0 +1,7 @@
+"""Allow ``python -m avalon_cli``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

avalon_cli-0.2.0/src/avalon_cli/cli.py

@@ -0,0 +1,163 @@
+"""The ``avalon`` command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import platform
+import shlex
+import signal
+import sys
+import threading
+from collections.abc import Sequence
+from typing import TextIO
+
+from . import __version__
+from .config import ConfigError, load_config
+from .reloader import DevServer, build_command
+from .scaffold import ScaffoldError, create_project
+from .templates import DEFAULT_TEMPLATE, TEMPLATES
+
+__all__ = ["build_parser", "main"]
+
+
+class CLIError(Exception):
+    """An error reported to the user as ``error: <message>`` with exit code 1."""
+
+
+def _cmd_new(args: argparse.Namespace, out: TextIO) -> int:
+    result = create_project(args.name, args.template, args.directory, force=args.force)
+    out.write(f"Created {result.template!r} project in {result.root}\n")
+    for path in result.files:
+        out.write(f"  {path.relative_to(result.root).as_posix()}\n")
+    out.write(f"\nNext steps:\n  cd {shlex.quote(str(result.root))}\n  avalon dev\n")
+    return 0
+
+
+def _cmd_templates(args: argparse.Namespace, out: TextIO) -> int:
+    width = max(len(name) for name in TEMPLATES)
+    for name in sorted(TEMPLATES):
+        marker = " (default)" if name == DEFAULT_TEMPLATE else ""
+        out.write(f"{name:<{width}}  {TEMPLATES[name].description}{marker}\n")
+    return 0
+
+
+def _cmd_info(args: argparse.Namespace, out: TextIO) -> int:
+    out.write(f"avalon-cli  {__version__}\n")
+    out.write(f"python      {platform.python_version()} ({sys.executable})\n")
+    try:
+        config = load_config(args.project)
+    except ConfigError as exc:
+        out.write(f"project     (none: {exc})\n")
+        return 0
+    dev = config.dev
+    argv = build_command(dev.command, host=dev.host, port=dev.port)
+    out.write(f"project     {config.name}\n")
+    out.write(f"root        {config.root}\n")
+    out.write(f"command     {shlex.join(argv)}\n")
+    out.write(f"address     http://{dev.host}:{dev.port}/\n")
+    out.write(f"watch       {', '.join(dev.watch)}\n")
+    out.write(f"extensions  {', '.join(dev.extensions) or '(all files)'}\n")
+    return 0
+
+
+def _cmd_dev(args: argparse.Namespace, out: TextIO) -> int:
+    config = load_config(args.project)
+    dev = config.dev
+    host = dev.host if args.host is None else args.host
+    port = dev.port if args.port is None else args.port
+    interval = dev.interval if args.interval is None else args.interval
+    if not 0 < port < 65536:
+        raise CLIError(f"port must be between 1 and 65535 (got {port})")
+    if interval <= 0:
+        raise CLIError("interval must be positive")
+    argv = build_command(dev.command, host=host, port=port)
+
+    env = dict(os.environ)
+    env.update(AVALON_HOST=host, AVALON_PORT=str(port), AVALON_ENV="development")
+    server = DevServer(
+        argv,
+        cwd=config.root,
+        env=env,
+        watch=dev.watch,
+        extensions=dev.extensions,
+        ignore=dev.ignore,
+        interval=interval,
+        reload=not args.no_reload,
+    )
+    out.write(f"Serving {config.name} at http://{host}:{port}/ (Ctrl-C to stop)\n")
+    out.flush()
+
+    # Treat SIGTERM like a clean shutdown so the child is never orphaned.
+    stop_event = threading.Event()
+    previous = None
+    if threading.current_thread() is threading.main_thread():
+        previous = signal.signal(signal.SIGTERM, lambda signum, frame: stop_event.set())
+    try:
+        return server.run(stop_event)
+    except KeyboardInterrupt:
+        out.write("\nStopped.\n")
+        return 130
+    finally:
+        if previous is not None:
+            signal.signal(signal.SIGTERM, previous)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the argument parser for the ``avalon`` command."""
+    parser = argparse.ArgumentParser(
+        prog="avalon",
+        description="Command-line companion for the Avalon real-time web framework.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND", required=True)
+
+    new = sub.add_parser("new", help="create a new project from a template")
+    new.add_argument("name", help="project name (also the directory name)")
+    new.add_argument(
+        "-t", "--template", default=DEFAULT_TEMPLATE, choices=sorted(TEMPLATES),
+        help=f"template to use (default: {DEFAULT_TEMPLATE})",
+    )
+    new.add_argument(
+        "-d", "--directory", default=".",
+        help="parent directory to create the project in (default: current directory)",
+    )
+    new.add_argument("--force", action="store_true", help="write into a non-empty directory")
+    new.set_defaults(handler=_cmd_new)
+
+    dev = sub.add_parser("dev", help="run the dev command with auto-reload")
+    dev.add_argument("-C", "--project", default=".", help="project directory (default: current directory)")
+    dev.add_argument("--host", help="host to bind (overrides avalon.toml)")
+    dev.add_argument("-p", "--port", type=int, help="port to bind (overrides avalon.toml)")
+    dev.add_argument("--interval", type=float, help="seconds between file-change polls")
+    dev.add_argument("--no-reload", action="store_true", help="run once without watching files")
+    dev.set_defaults(handler=_cmd_dev)
+
+    templates = sub.add_parser("templates", help="list available project templates")
+    templates.set_defaults(handler=_cmd_templates)
+
+    info = sub.add_parser("info", help="show environment and resolved project settings")
+    info.add_argument("-C", "--project", default=".", help="project directory (default: current directory)")
+    info.set_defaults(handler=_cmd_info)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None, out: TextIO | None = None) -> int:
+    """Entry point for the ``avalon`` console script.
+
+    :param argv: arguments excluding the program name (defaults to ``sys.argv[1:]``).
+    :param out: stream for normal output (defaults to ``sys.stdout``).
+    :returns: process exit code. Errors print ``error: ...`` to stderr and return 1.
+    """
+    out = out or sys.stdout
+    args = build_parser().parse_args(argv)
+    try:
+        return args.handler(args, out)
+    except (CLIError, ConfigError, ScaffoldError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())