CLI Reference¶

Command-line interface reference for cosalette applications. The CLI is built automatically by App.run() using Typer, aligning with the framework's type-hint-driven philosophy (see ADR-005).

Usage¶

myapp [OPTIONS]

The executable name depends on your project's entry point configuration (see Build a Full App for packaging details).

Options¶

Exit Codes¶

EXIT_CONFIG_ERROR also covers an invalid COSALETTE_LOOP_STALL_TIMEOUT. A loop stalled inside C code that holds the GIL ends through the watchdog's faulthandler backstop instead, after twice the timeout and with code 1, not 6. On stderr it shows faulthandler's Timeout (H:MM:SS)! header (Timeout (0:10:00)! for a 300 s timeout) followed by every thread's stack, with no CRITICAL cosalette: event loop stalled line. restart: on-failure and unless-stopped still restart the container on code 1.

The health subcommand has its own exit codes: 0 healthy, 1 unhealthy.

Log Levels¶

Valid values for --log-level (case-insensitive):

Log Formats¶

Valid values for --log-format (case-insensitive):

Example¶

# Run with defaults (loads .env, JSON logging at INFO)
myapp

# Development mode: text logs at DEBUG level
myapp --log-level DEBUG --log-format text

# Dry-run with a custom env file
myapp --dry-run --env-file config/staging.env

# Check the version
myapp --version

# Show all registered devices as a table
myapp --show-devices

# Show registrations as JSON (useful for AI agents and scripts)
myapp --show-devices-json

Introspection Flags¶

The --show-devices and --show-devices-json flags are eager — they run immediately after argument parsing and exit before settings validation. This means they work even when the .env file is missing or contains invalid values, making them useful for debugging configuration problems.

--show-devices renders a human-readable table sourced from the app's AsyncAPI document (app.asyncapi()), grouped by channel archetype (devices, telemetry, commands). It is not the registry snapshot and carries no adapters section — despite the flag name. Empty sections are omitted. To render the registry snapshot instead — including periodic tasks and per-entity trigger sources — use cosalette manifest --registry. See Registry Introspection for the snapshot structure.

--show-devices-json outputs the same AsyncAPI data as indented JSON, suitable for piping into jq or consumption by AI coding agents. When both flags are given, --show-devices-json takes precedence.

Health Probe¶

cosalette-health, cosalette health and myapp health check the health file that the app writes when the COSALETTE_HEALTH_FILE environment variable names a path (ADR-083, Health File). None of them loads settings or connects to the broker. Use them only where an orchestrator acts on the result: a Kubernetes liveness probe, a Docker Swarm service or an autoheal container. Plain Docker only marks a container unhealthy, so most deployments watch the MQTT signals and rely on a restart policy instead.

Prefer cosalette-health in probe commands. It is a native binary in the platform wheels and a stdlib-only Python script elsewhere (ADR-087), so a run costs about 1 ms instead of the Python interpreter start and framework import that cosalette health and myapp health pay (about 390 ms on a desktop CPU, seconds on a Raspberry Pi). All three take the same options and give the same result.

The probe exits 0 and prints the file's age when the file is fresh and no device has a failing status. It exits 1 and prints the reason on stderr when the file is missing, unreadable or too old, or when a device has a failing status. A usage error in the health arguments, such as --max-age -1 or an unknown option, also exits 1, with unhealthy: usage error: <message> on stderr, because Docker reserves exit code 2. cosalette-health --help exits 0. See Health Checks.

Registry Snapshot¶

The app-runtime --show-devices flags above are AsyncAPI-sourced. To inspect the registry snapshot — the flat view of registrations that also covers periodic tasks (which have no AsyncAPI channel by construction, ADR-041) and each entity's trigger_source / min_interval — use the cosalette package CLI:

# Registry snapshot as JSON
cosalette manifest myapp.main:app --registry

# Registry snapshot as a human-readable table
cosalette manifest myapp.main:app --registry --table

The table adds Trigger and Min interval columns to the Devices and Telemetry sections, showing an em-dash for non-triggerable entities. Without --registry, manifest and manifest --table emit the AsyncAPI document exactly as before.