# _cli URL: /pounce/api/_cli/ Section: api Description: Command-line interface for pounce. Provides the ``pounce`` command with subcommands:: pounce serve --app myapp:app --host 0.0.0.0 --port 8000 --workers 4 Built on milo-cli for type-driven parsing, MCP server, and llms.txt generation. --- > For a complete page index, fetch /pounce/llms.txt. Open LLM text (/pounce/api/_cli/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_cli%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_cli%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_cli%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_cli%2Findex.txt) Module # `_cli` Command-line interface for pounce. Provides the`pounce`command with subcommands:: ``` pounce serve --app myapp:app --host 0.0.0.0 --port 8000 --workers 4 ``` Built on milo-cli for type-driven parsing, MCP server, and llms.txt generation. 1Class28Functions ## Classes `_PounceCLI` 0 ▼ CLI subclass that renders Milo metadata with Pounce branding. Bases: `CLI` CLI subclass that renders Milo metadata with Pounce branding. ## Functions `_render_help_state` 1 `str` ▼ Render Milo help metadata through Pounce's branded template. `def _render_help_state(state: HelpState) -> str` ##### Parameters Name Type Description `state` `HelpState` ##### Returns `str` `_render_plain_help` 1 `str` ▼ Render dependency-free plain help when the branded template fails. `def _render_plain_help(state: HelpState) -> str` ##### Parameters Name Type Description `state` `HelpState` ##### Returns `str` `_write_help` 1 `None` ▼ Write one complete help report to stdout. `def _write_help(state: HelpState) -> None` ##### Parameters Name Type Description `state` `HelpState` `_config_epilog_for` 1 `str` ▼ Return the TOML escape-hatch footer for serve/check help. `def _config_epilog_for(prog: str) -> str` ##### Parameters Name Type Description `prog` `str` ##### Returns `str` `serve` 36 `None` ▼ Start the ASGI server. Accepts an ASGI application reference (e.g., 'myapp:app… `def serve(app: str, config: str | None = None, host: str | None = None, port: int | None = None, workers: int | None = None, worker_mode: str | None = None, cpu_affinity: bool = False, log_level: str | None = None, log_format: str | None = None, root_path: str | None = None, no_compression: bool = False, server_timing: bool = False, no_access_log: bool = False, ssl_certfile: str | None = None, ssl_keyfile: str | None = None, no_http2: bool = False, http3: bool = False, reload: bool = False, reload_include: str | None = None, reload_dir: list[str] | None = None, keep_alive_timeout: float | None = None, header_timeout: float | None = None, request_timeout: float | None = None, write_timeout: float | None = None, startup_timeout: float | None = None, max_requests_per_connection: int | None = None, shutdown_timeout: float | None = None, uds: str | None = None, health_check_path: str | None = None, debug: bool = False, trusted_hosts: str | None = None, metrics: bool = False, app_name: str | None = None, app_tagline: str | None = None, app_version: str | None = None, signage: str | None = None) -> None` Start the ASGI server. Accepts an ASGI application reference (e.g., 'myapp:app' or 'myapp:create_app()') and starts serving it. ##### Parameters Name Type Description `app` `str` ASGI application (e.g.,`myapp:app` or `myapp:create_app()`). `config` `str | None` Path to pounce.toml or pyproject.toml; auto-detected if omitted. Default:`None` `host` `str | None` Bind address. Default:`None` `port` `int | None` Bind port. Default:`None` `workers` `int | None` Number of workers; zero selects the automatic default. Default:`None` `worker_mode` `str | None` Worker model: auto, sync, async, or subinterpreter. Default:`None` `cpu_affinity` `bool` Pin each worker to a CPU core on Linux. Default:`False` `log_level` `str | None` Log level. Default:`None` `log_format` `str | None` Log format: auto, text, or json. Default:`None` `root_path` `str | None` ASGI root path for reverse-proxy setups. Default:`None` `no_compression` `bool` Disable response compression. Default:`False` `server_timing` `bool` Enable Server-Timing header injection. Default:`False` `no_access_log` `bool` Disable access logging. Default:`False` `ssl_certfile` `str | None` TLS certificate path; enables HTTPS. Default:`None` `ssl_keyfile` `str | None` TLS private-key path. Default:`None` `no_http2` `bool` Disable h2 ALPN advertisement and force HTTP/1.1 at the origin. Default:`False` `http3` `bool` Enable HTTP/3; requires TLS and the h3 extra. Default:`False` `reload` `bool` Reload automatically when source files change. Default:`False` `reload_include` `str | None` Extra file extensions to watch, comma-separated. Default:`None` `reload_dir` `list[str] | None` Extra directories to watch; may be repeated. Default:`None` `keep_alive_timeout` `float | None` Idle keep-alive timeout in seconds. Default:`None` `header_timeout` `float | None` Header receive timeout in seconds. Default:`None` `request_timeout` `float | None` Request-body receive timeout in seconds. Default:`None` `write_timeout` `float | None` Blocked response-write timeout in seconds. Default:`None` `startup_timeout` `float | None` Maximum lifespan-startup wait in seconds. Default:`None` `max_requests_per_connection` `int | None` Requests per connection; zero is unlimited. Default:`None` `shutdown_timeout` `float | None` Maximum worker-shutdown wait in seconds. Default:`None` `uds` `str | None` Unix domain socket path. Default:`None` `health_check_path` `str | None` Built-in readiness endpoint path. Default:`None` `debug` `bool` Enable rich error pages; never enable in production. Default:`False` `trusted_hosts` `str | None` Trusted proxy hostnames, comma-separated. Default:`None` `metrics` `bool` Enable the Prometheus metrics endpoint. Default:`False` `app_name` `str | None` Application name displayed in the startup banner. Default:`None` `app_tagline` `str | None` Short description displayed below the application name. Default:`None` `app_version` `str | None` Application version displayed in the startup banner. Default:`None` `signage` `str | None` Banner layout: full, minimal, or off. Default:`None` `_serve_impl` 36 `None` ▼ Inner serve implementation — raises on error, no catching. `def _serve_impl(*, app: str, config: str | None, host: str | None, port: int | None, workers: int | None, log_level: str | None, log_format: str | None, root_path: str | None, no_compression: bool, server_timing: bool, no_access_log: bool, ssl_certfile: str | None, ssl_keyfile: str | None, no_http2: bool, http3: bool, reload: bool, reload_include: str | None, reload_dir: list[str] | None, keep_alive_timeout: float | None, header_timeout: float | None, request_timeout: float | None, write_timeout: float | None, startup_timeout: float | None, max_requests_per_connection: int | None, shutdown_timeout: float | None, uds: str | None, health_check_path: str | None, debug: bool, trusted_hosts: str | None, metrics: bool, worker_mode: str | None, cpu_affinity: bool, app_name: str | None, app_tagline: str | None, app_version: str | None, signage: str | None) -> None` ##### Parameters Name Type Description `app` `str` `config` `str | None` `host` `str | None` `port` `int | None` `workers` `int | None` `log_level` `str | None` `log_format` `str | None` `root_path` `str | None` `no_compression` `bool` `server_timing` `bool` `no_access_log` `bool` `ssl_certfile` `str | None` `ssl_keyfile` `str | None` `no_http2` `bool` `http3` `bool` `reload` `bool` `reload_include` `str | None` `reload_dir` `list[str] | None` `keep_alive_timeout` `float | None` `header_timeout` `float | None` `request_timeout` `float | None` `write_timeout` `float | None` `startup_timeout` `float | None` `max_requests_per_connection` `int | None` `shutdown_timeout` `float | None` `uds` `str | None` `health_check_path` `str | None` `debug` `bool` `trusted_hosts` `str | None` `metrics` `bool` `worker_mode` `str | None` `cpu_affinity` `bool` `app_name` `str | None` `app_tagline` `str | None` `app_version` `str | None` `signage` `str | None` `_die` 5 `None` ▼ Render a branded error and exit. ``code`` is a semantic ``POUNCE__`` identifie… `def _die(message: str, *, hint: str | None = None, code: str | None = None, doc: str | None = None, diagnostics: list[dict[str, str]] | None = None) -> None` Render a branded error and exit. `code` (/pounce/api/protocols/_base/#WebSocketDisconnected) is a semantic `POUNCE__` identifier; `doc` is the troubleshooting anchor (e.g.`docs/troubleshooting.md#POUNCE_X_Y`). Both are surfaced through `_output.error` (/pounce/api/_output/#error) to `error.kida`for rendering and let an agent reading stderr navigate from a failure to its catalog entry without grepping. ##### Parameters Name Type Description `message` `str` `hint` `str | None` Default:`None` `code` `str | None` Default:`None` `doc` `str | None` Default:`None` `diagnostics` `list[dict[str, str]] | None` Default:`None` `_hint_for_import_error` 1 `str | None` ▼ Return a hint for common import/app-path errors. `def _hint_for_import_error(exc: Exception) -> str | None` ##### Parameters Name Type Description `exc` `Exception` ##### Returns `str | None` `_diagnostics_for_import_error` 1 `list[dict[str, str]] | N…` ▼ Return diagnostic context for import errors. `def _diagnostics_for_import_error(exc: Exception) -> list[dict[str, str]] | None` ##### Parameters Name Type Description `exc` `Exception` ##### Returns `list[dict[str, str]] | None` `_hint_for_os_error` 1 `str | None` ▼ Return a hint for common OS-level errors. `def _hint_for_os_error(exc: OSError) -> str | None` ##### Parameters Name Type Description `exc` `OSError` ##### Returns `str | None` `_diagnostics_for_os_error` 1 `list[dict[str, str]] | N…` ▼ Return diagnostic context for OS errors (e.g. who holds the port). `def _diagnostics_for_os_error(exc: OSError) -> list[dict[str, str]] | None` ##### Parameters Name Type Description `exc` `OSError` ##### Returns `list[dict[str, str]] | None` `_hint_for_pounce_error` 1 `str | None` ▼ Return a hint for pounce-specific errors. `def _hint_for_pounce_error(exc: Exception) -> str | None` ##### Parameters Name Type Description `exc` `Exception` ##### Returns `str | None` `parse_extensions` 1 `tuple[str, ...]` ▼ Parse a comma-separated extensions string into a normalized tuple. Ensures eac… `def parse_extensions(raw: str | None) -> tuple[str, ...]` Parse a comma-separated extensions string into a normalized tuple. Ensures each extension starts with a dot and strips whitespace. Empty entries are filtered out. ##### Parameters Name Type Description `raw` `str | None` Comma-separated string (e.g.`".html,.css,md"`), or None. ##### Returns `tuple[str, ...]` `parse_dirs` 1 `tuple[str, ...]` ▼ Parse a list of directory strings into a cleaned tuple. Strips whitespace and … `def parse_dirs(raw: list[str] | None) -> tuple[str, ...]` Parse a list of directory strings into a cleaned tuple. Strips whitespace and filters empty entries. ##### Parameters Name Type Description `raw` `list[str] | None` List of directory paths, or None. ##### Returns `tuple[str, ...]` `parse_hosts` 1 `tuple[str, ...]` ▼ Parse a comma-separated host list into a normalized tuple. `def parse_hosts(raw: str | None) -> tuple[str, ...]` ##### Parameters Name Type Description `raw` `str | None` Comma-separated hostnames (e.g.`"localhost,127.0.0.1"`), or None. ##### Returns `tuple[str, ...]` `info` 1 `None` ▼ Display system info, dependency status, and environment diagnostics. Pass ``--… `def info(output_format: str = 'text') -> None` Display system info, dependency status, and environment diagnostics. Pass`--output-format json`for a stable, machine-readable dict suitable for`pounce info --output-format json | jq`. ##### Parameters Name Type Description `output_format` `str` Output format: text or json. Default:`'text'` `check` 36 `None` ▼ Run pre-flight validation checks. Takes the same arguments as ``serve`` and va… `def check(app: str, config: str | None = None, host: str | None = None, port: int | None = None, workers: int | None = None, worker_mode: str | None = None, cpu_affinity: bool = False, log_level: str | None = None, log_format: str | None = None, root_path: str | None = None, no_compression: bool = False, server_timing: bool = False, no_access_log: bool = False, ssl_certfile: str | None = None, ssl_keyfile: str | None = None, no_http2: bool = False, http3: bool = False, reload: bool = False, reload_include: str | None = None, reload_dir: list[str] | None = None, keep_alive_timeout: float | None = None, header_timeout: float | None = None, request_timeout: float | None = None, write_timeout: float | None = None, startup_timeout: float | None = None, max_requests_per_connection: int | None = None, shutdown_timeout: float | None = None, uds: str | None = None, health_check_path: str | None = None, debug: bool = False, trusted_hosts: str | None = None, metrics: bool = False, app_name: str | None = None, app_tagline: str | None = None, app_version: str | None = None, signage: str | None = None) -> None` Run pre-flight validation checks. Takes the same arguments as`serve`and validates them without starting the server. Exits with code 1 if any check fails. ##### Parameters Name Type Description `app` `str` ASGI application (e.g.,`myapp:app` or `myapp:create_app()`). `config` `str | None` Path to pounce.toml or pyproject.toml; auto-detected if omitted. Default:`None` `host` `str | None` Bind address. Default:`None` `port` `int | None` Bind port. Default:`None` `workers` `int | None` Number of workers; zero selects the automatic default. Default:`None` `worker_mode` `str | None` Worker model: auto, sync, async, or subinterpreter. Default:`None` `cpu_affinity` `bool` Pin each worker to a CPU core on Linux. Default:`False` `log_level` `str | None` Log level. Default:`None` `log_format` `str | None` Log format: auto, text, or json. Default:`None` `root_path` `str | None` ASGI root path for reverse-proxy setups. Default:`None` `no_compression` `bool` Disable response compression. Default:`False` `server_timing` `bool` Enable Server-Timing header injection. Default:`False` `no_access_log` `bool` Disable access logging. Default:`False` `ssl_certfile` `str | None` TLS certificate path; enables HTTPS. Default:`None` `ssl_keyfile` `str | None` TLS private-key path. Default:`None` `no_http2` `bool` Disable h2 ALPN advertisement and force HTTP/1.1 at the origin. Default:`False` `http3` `bool` Enable HTTP/3; requires TLS and the h3 extra. Default:`False` `reload` `bool` Reload automatically when source files change. Default:`False` `reload_include` `str | None` Extra file extensions to watch, comma-separated. Default:`None` `reload_dir` `list[str] | None` Extra directories to watch; may be repeated. Default:`None` `keep_alive_timeout` `float | None` Idle keep-alive timeout in seconds. Default:`None` `header_timeout` `float | None` Header receive timeout in seconds. Default:`None` `request_timeout` `float | None` Request-body receive timeout in seconds. Default:`None` `write_timeout` `float | None` Blocked response-write timeout in seconds. Default:`None` `startup_timeout` `float | None` Maximum lifespan-startup wait in seconds. Default:`None` `max_requests_per_connection` `int | None` Requests per connection; zero is unlimited. Default:`None` `shutdown_timeout` `float | None` Maximum worker-shutdown wait in seconds. Default:`None` `uds` `str | None` Unix domain socket path. Default:`None` `health_check_path` `str | None` Built-in readiness endpoint path. Default:`None` `debug` `bool` Enable rich error pages; never enable in production. Default:`False` `trusted_hosts` `str | None` Trusted proxy hostnames, comma-separated. Default:`None` `metrics` `bool` Enable the Prometheus metrics endpoint. Default:`False` `app_name` `str | None` Application name displayed in the startup banner. Default:`None` `app_tagline` `str | None` Short description displayed below the application name. Default:`None` `app_version` `str | None` Application version displayed in the startup banner. Default:`None` `signage` `str | None` Banner layout: full, minimal, or off. Default:`None` `_check_app_importable` 1 `dict[str, str]` ▼ Try to import the app and return a check result. `def _check_app_importable(app: str) -> dict[str, str]` ##### Parameters Name Type Description `app` `str` ##### Returns `dict[str, str]` `_check_port_available` 2 `dict[str, str]` ▼ Try to bind the port and return a check result. `def _check_port_available(host: str, port: int) -> dict[str, str]` ##### Parameters Name Type Description `host` `str` `port` `int` ##### Returns `dict[str, str]` `_check_tls_cert` 2 `dict[str, str]` ▼ Validate TLS certificate file exists and is loadable. `def _check_tls_cert(certfile: str, keyfile: str | None = None) -> dict[str, str]` ##### Parameters Name Type Description `certfile` `str` `keyfile` `str | None` Default:`None` ##### Returns `dict[str, str]` `_check_deps_for_config` 2 `list[dict[str, str]]` ▼ Check that optional deps are installed for requested features. `def _check_deps_for_config(*, http3: bool, ssl_certfile: str | None) -> list[dict[str, str]]` ##### Parameters Name Type Description `http3` `bool` `ssl_certfile` `str | None` ##### Returns `list[dict[str, str]]` `_check_config_valid` 27 `dict[str, str]` ▼ Try to construct ServerConfig and catch validation errors. `def _check_config_valid(*, host: str, port: int, workers: int, worker_mode: str, cpu_affinity: bool, log_level: str, log_format: str, root_path: str, no_compression: bool, server_timing: bool, no_access_log: bool, ssl_certfile: str | None, ssl_keyfile: str | None, no_http2: bool, http3: bool, reload: bool, reload_include: str | None, reload_dir: list[str] | None, keep_alive_timeout: float, header_timeout: float, request_timeout: float, write_timeout: float, startup_timeout: float, max_requests_per_connection: int, shutdown_timeout: float, uds: str | None, health_check_path: str | None) -> dict[str, str]` ##### Parameters Name Type Description `host` `str` `port` `int` `workers` `int` `worker_mode` `str` `cpu_affinity` `bool` `log_level` `str` `log_format` `str` `root_path` `str` `no_compression` `bool` `server_timing` `bool` `no_access_log` `bool` `ssl_certfile` `str | None` `ssl_keyfile` `str | None` `no_http2` `bool` `http3` `bool` `reload` `bool` `reload_include` `str | None` `reload_dir` `list[str] | None` `keep_alive_timeout` `float` `header_timeout` `float` `request_timeout` `float` `write_timeout` `float` `startup_timeout` `float` `max_requests_per_connection` `int` `shutdown_timeout` `float` `uds` `str | None` `health_check_path` `str | None` ##### Returns `dict[str, str]` `_check_merged_config_valid` 1 `dict[str, str]` ▼ Try to construct ServerConfig from merged config dict and catch validation erro… `def _check_merged_config_valid(merged: dict[str, object]) -> dict[str, str]` Try to construct ServerConfig from merged config dict and catch validation errors. ##### Parameters Name Type Description `merged` `dict[str, object]` ##### Returns `dict[str, str]` `_check_signage` 1 `dict[str, str]` ▼ Validate signage value. `def _check_signage(signage: str) -> dict[str, str]` ##### Parameters Name Type Description `signage` `str` ##### Returns `dict[str, str]` `init` 2 `None` ▼ Write ``app.py``, ``pounce.toml``, and ``.gitignore`` into *directory* (current… `def init(directory: str | None = None, force: bool = False) -> None` Write`app.py`, `pounce.toml`, and `.gitignore`into directory (current working directory by default). Refuses to overwrite existing scaffold files unless`--force`is set. Intended for fresh directories — real projects already have their own app and config. ##### Parameters Name Type Description `directory` `str | None` Target directory; defaults to the current directory. Default:`None` `force` `bool` Overwrite existing scaffold files. Default:`False` `config_schema` 1 `None` ▼ Print a machine-readable description of every ServerConfig field. ``--output-f… `def config_schema(output_format: str = 'json') -> None` Print a machine-readable description of every ServerConfig field. `--output-format json`(default) emits a JSON Schema Draft 2020-12 document with types, defaults, and enum constraints. `--output-format toml-template` emits a commented `pounce.toml` skeleton ready to uncomment and edit. ##### Parameters Name Type Description `output_format` `str` Output format: json or toml-template. Default:`'json'` `config_show` 5 `None` ▼ Print the active ServerConfig through the Sprint 0.3 redaction allowlist. ``co… `def config_show(config: str | None = None, output_format: str = 'toml', host: str | None = None, port: int | None = None, workers: int | None = None) -> None` Print the active ServerConfig through the Sprint 0.3 redaction allowlist. `config show`merges TOML, defaults, and its limited display overrides (`host`, `port`, and `workers`). It is not a full mirror of every `serve`flag. Secrets and filesystem paths are never printed — fields classified as `REDACT_TO_BOOL` appear as `_set = true|false`, and fields outside the allowlist are omitted entirely. ##### Parameters Name Type Description `config` `str | None` Path to pounce.toml or pyproject.toml; auto-detected if omitted. Default:`None` `output_format` `str` Output format: toml or json. Default:`'toml'` `host` `str | None` Override the displayed bind address. Default:`None` `port` `int | None` Override the displayed bind port. Default:`None` `workers` `int | None` Override the displayed worker count. Default:`None` `main` 1 `None` ▼ Entry point for the ``pounce`` CLI command. `def main(args: list[str] | None = None) -> None` ##### Parameters Name Type Description `args` `list[str] | None` Command-line arguments (defaults to sys.argv[1:]). Default:`None`