awa-cli
Command-line interface for the Awa Postgres-native job queue. Run migrations, inspect and manage jobs, walk the storage transition, drive the Dead Letter Queue, list cron schedules, and serve the web admin UI.
Install
The CLI is shipped as both a Rust binary and a Python wheel. Either distribution gives you the same awa executable, including the embedded React admin dashboard for awa serve.
# Python (no Rust toolchain needed)
pip install awa-cli
# Rust
cargo install awa-cli
If you're already using the awa-pg Python SDK, install both with one command:
pip install 'awa-pg[ui]'
That pulls in awa-cli as a dependency so python -m awa serve works end-to-end alongside the worker SDK.
Quick start
# Run migrations
awa --database-url $DATABASE_URL migrate
# Inspect
awa --database-url $DATABASE_URL queue stats
awa --database-url $DATABASE_URL job list --state failed
awa --database-url $DATABASE_URL job dump 12345
awa --database-url $DATABASE_URL job dump-run 12345
# Admin
awa --database-url $DATABASE_URL job retry 12345
awa --database-url $DATABASE_URL queue pause email
awa --database-url $DATABASE_URL queue drain email
# Web UI
awa --database-url $DATABASE_URL serve
# → http://127.0.0.1:3000
DATABASE_URL may be passed as the --database-url flag or read from the environment.
Commands
| Command | Description |
|---|---|
migrate |
Apply migrations, or extract / print SQL with --sql / --extract-to |
job list |
List jobs with --state / --kind / --queue filters |
job dump <id> |
Pretty-print one job and its full lifecycle metadata |
job dump-run <id> [--attempt N] |
Pretty-print one attempt run |
job retry <id> |
Retry a failed or cancelled job |
job cancel <id> |
Cancel a job |
job retry-failed (--kind K | --queue Q) |
Retry every failed job matching exactly one filter |
job discard --kind K |
Delete every failed job of a given kind |
queue stats |
Per-queue depth, lag, and throughput |
queue pause / resume / drain <queue> |
Queue admin |
cron list / remove |
List or remove cron schedules |
dlq depth [--queue Q] |
Total DLQ rows, optionally split by queue |
dlq list |
List DLQ entries with --kind / --queue / --tag / --before-* filters |
dlq retry <id> |
Retry a single DLQ row |
dlq retry-bulk |
Retry every DLQ row matching the filter (--all required if no filter is given) |
dlq move |
Move existing failed terminal rows into the DLQ |
dlq purge |
Delete DLQ rows matching the filter (--all required if no filter is given) |
storage status |
Current storage-transition state |
storage prepare --engine E |
Prepare a future storage engine without changing routing |
storage prepare-queue-storage-schema |
Materialize the queue-storage schema (tables, indexes, functions) |
storage enter-mixed-transition |
Begin routing new writes to the prepared engine |
storage finalize |
Finalize the transition once drain and capability gates pass |
storage abort |
Abort a prepared or mixed-transition rollout |
serve |
Start the embedded web admin UI |
Run awa <command> --help for the flags on any subcommand.
Storage transition
For an existing 0.5.x cluster moving to the queue-storage engine, the typical sequence is:
awa --database-url $DATABASE_URL storage prepare-queue-storage-schema
awa --database-url $DATABASE_URL storage prepare --engine queue_storage
# ... roll out a binary that supports queue storage to all workers ...
awa --database-url $DATABASE_URL storage enter-mixed-transition
# ... drain the canonical engine ...
awa --database-url $DATABASE_URL storage finalize
See docs/upgrade-0.5-to-0.6.md for the full pre-flight checklist, gate semantics, and rollback notes. Fresh installs auto-finalize on first migrate and do not need this sequence.
Dead Letter Queue
dlq retry-bulk and dlq purge require an explicit filter (--kind, --queue, or --tag) or --all. This is intentional — a bare bulk retry / purge with no filter would touch every DLQ row, which is almost never what you want. See docs/dead-letter-queue.md.
Web UI
awa serve starts an embedded admin UI (awa-ui) bound to 127.0.0.1:3000 by default. The UI is read-only when the database reports transaction_read_only = on (e.g. on a replica) or when --read-only is passed explicitly. Mutation endpoints return 503 in that mode.
License
MIT OR Apache-2.0
1 maintainer
Release files for awa-cli 0.6.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| awa_cli-0.6.9-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | Python 3 | none | Linux glibc 2.17+ x86-64 | Details |
| awa_cli-0.6.9-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | Python 3 | none | Linux glibc 2.17+ ARM64 | Details |
| awa_cli-0.6.9-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details |
| awa_cli-0.6.9-py3-none-macosx_10_12_x86_64.whl | Python 3 | none | macOS 10.12+ x86-64 | Details |
Total release size: 21.5 MB
Release files / awa_cli-0.6.9-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | awa_cli-0.6.9-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 5.5 MB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
8886907c98a55cf617f8aa33ee8bdb5b94dade6372f216c5e9f9f4d57dba1de6
|
|
BLAKE2b-256 checksum How to use checksums |
d09cfda31ec7b98a0cc98e361d52316aa844fd36867c96aea0560385c8583472
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency logRelease files / awa_cli-0.6.9-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | awa_cli-0.6.9-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 5.4 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
c194f2bb6f2cf01eb7eb758dcfe828dfc845f1fe7935510f92bff8f2c703d61d
|
|
BLAKE2b-256 checksum How to use checksums |
fe87c49bfa349042dc3b509c9990e253128a1e7233b1f0c575043c9bfd2fb3b0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency logRelease files / awa_cli-0.6.9-py3-none-macosx_11_0_arm64.whl
| Download URL | awa_cli-0.6.9-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 5.2 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
aa9d060ca331cd7ef9cfd35e8804a75c522ecb5929ae2e568248ee79b6687a03
|
|
BLAKE2b-256 checksum How to use checksums |
bd49e9ccfc99a3dea64e0df72b84bb78175dca2a19551968f7afcb54313ce725
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency logRelease files / awa_cli-0.6.9-py3-none-macosx_10_12_x86_64.whl
| Download URL | awa_cli-0.6.9-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 5.4 MB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
3f5c61fdb8c8fed59c518bd54d8513f952af096a39ed8fd0cfe7d766cacb5cd2
|
|
BLAKE2b-256 checksum How to use checksums |
fd3121ca1c04000374f54f674ef01349803adbb30da3f0d9daf470b13b5bcda8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency log
