Skip to content

CLI Reference

This page is deterministically generated from litestar_queues.cli.queues_group via uv run python tools/docs/generate_cli_docs.py.

All commands run under the Litestar CLI queues group:

litestar --app app:app queues <command> [OPTIONS]
Command Category Summary
litestar queues run Worker & Consumer Execution Start a standalone worker fleet.
litestar queues run-consumer Worker & Consumer Execution Start a continuous external broker consumer.
litestar queues run-task Worker & Consumer Execution Run one queued record by id (external-executor consumer). By default reads the task id QUEUES_TASK_ID and QUEUES_CONFIG_FACTORY from the environment; the options below override those defaults so a job can be run by hand.
litestar queues run-maintenance Maintenance, Status & Diagnostics Run one bounded maintenance pass (external reconcile, stale recovery, and retention) and exit. Thresholds and limits come from QueueConfig.maintenance; this command never starts a worker or runs due work.
litestar queues status Maintenance, Status & Diagnostics Show queue status counts.
litestar queues scheduler-health Maintenance, Status & Diagnostics Exit non-zero if the scheduler canary task has not completed within the window.

Worker & Consumer Execution

Commands for running queue workers, broker push/pull consumers, and one-shot serverless task containers.

litestar queues run

Start a standalone worker fleet.

litestar queues run [OPTIONS]

Options

Option Type Default Description
--queue text None Queue name to process. Repeatable.
--max-concurrency integer range None Override WorkerConfig.max_concurrency for this run.
--drain-timeout float range None Seconds to wait for in-flight tasks to drain after SIGTERM/SIGINT. Defaults to QueueConfig.worker.graceful_shutdown_timeout.

litestar queues run-consumer

Start a continuous external broker consumer.

litestar queues run-consumer [OPTIONS]

Options

Option Type Default Description
--backend Choice required Configured broker backend to consume. (Choices: kafka, pubsub, rabbitmq, sqs)
--max-concurrency integer range None Command option.
--drain-timeout float range None Command option.

litestar queues run-task

Run one queued record by id (external-executor consumer). By default reads the task id QUEUES_TASK_ID and QUEUES_CONFIG_FACTORY from the environment; the options below override those defaults so a job can be run by hand.

litestar queues run-task [OPTIONS]

Options

Option Type Default Description
--task-id text None Run the queued record with this id (local one-shot).
--config-factory text None module:callable returning a QueueConfig or QueueService.
--task-modules text None Comma-separated modules to import before running the task.

Maintenance, Status & Diagnostics

Commands for executing the 6-phase queue maintenance sweep, inspecting backend health, and checking recurring scheduler heartbeats.

litestar queues run-maintenance

Run one bounded maintenance pass (external reconcile, stale recovery, and retention) and exit. Thresholds and limits come from QueueConfig.maintenance; this command never starts a worker or runs due work.

litestar queues run-maintenance [OPTIONS]

Options

Option Type Default Description
--phase Choice None Maintenance phase to run. Repeatable; defaults to every configured phase. Only narrows configuration. (Choices: expire, external, stale, schedules, terminal, events)
--json bool False Emit machine-readable JSON.

litestar queues status

Show queue status counts.

litestar queues status [OPTIONS]

Options

Option Type Default Description
--queue text None Count only records in this queue.
--json bool False Emit machine-readable JSON.

litestar queues scheduler-health

Exit non-zero if the scheduler canary task has not completed within the window.

litestar queues scheduler-health [OPTIONS]

Options

Option Type Default Description
--minutes integer range 5 Staleness threshold in minutes (default 5).

Public Python CLI Surface

cli

Public Click command facade for litestar queues CLI extensions.

queues_group 

queues_group()

register 

register(cli)

Attach the queues subcommand group to cli (idempotent).

run_command 

run_command(ctx, queues, max_concurrency, drain_timeout)

run_consumer_command 

run_consumer_command(ctx, backend, max_concurrency, drain_timeout)

run_task_command 

run_task_command(ctx, task_id, config_factory, task_modules)

run_maintenance_command 

run_maintenance_command(ctx, phases, as_json)

status_command 

status_command(ctx, queue_filter, as_json)

scheduler_health_command 

scheduler_health_command(ctx, minutes)