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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

awa_cli-0.6.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (5.6 MB view details)

Uploaded Jul 4, 2026 Python 3manylinux: glibc 2.17+ x86-64

awa_cli-0.6.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (5.4 MB view details)

Uploaded Jul 4, 2026 Python 3manylinux: glibc 2.17+ ARM64

awa_cli-0.6.0-py3-none-macosx_11_0_arm64.whl (5.2 MB view details)

Uploaded Jul 4, 2026 Python 3macOS 11.0+ ARM64

awa_cli-0.6.0-py3-none-macosx_10_12_x86_64.whl (5.4 MB view details)

Uploaded Jul 4, 2026 Python 3macOS 10.12+ x86-64

File details

Details for the file awa_cli-0.6.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: awa_cli-0.6.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Jul 4, 2026
Size: 5.6 MB
Tags: Python 3, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for awa_cli-0.6.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`48247b5747ae5bb48ef97ad46cc921d1ac45a9f7bc9a40f244bc3d649677364a`
MD5	`978b367952b7f3224f0dc3141713df30`
BLAKE2b-256	`e085d1a02c0e8e49dea97a08d6abb5ac6df94927f3e5346a4bcf9e414d618da0`

See more details on using hashes here.

Provenance

The following attestation bundles were made for awa_cli-0.6.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on hardbyte/awa

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: awa_cli-0.6.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: 48247b5747ae5bb48ef97ad46cc921d1ac45a9f7bc9a40f244bc3d649677364a
- Sigstore transparency entry: 2068035146
- Sigstore integration time: Jul 4, 2026
Source repository:
- Permalink: hardbyte/awa@671ca70e4ca38702fbe09a71653970f43ded0c8a
- Branch / Tag: refs/tags/v0.6.0
- Owner: https://github.com/hardbyte
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@671ca70e4ca38702fbe09a71653970f43ded0c8a
- Trigger Event: push

File details

Details for the file awa_cli-0.6.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

Download URL: awa_cli-0.6.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Upload date: Jul 4, 2026
Size: 5.4 MB
Tags: Python 3, manylinux: glibc 2.17+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for awa_cli-0.6.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm	Hash digest
SHA256	`d3d3961dd57c715d615b35f658d91389a20f96c5fd191c5426c1259d6f3d8bae`
MD5	`395fc951f2d022124f5a5d943d80e824`
BLAKE2b-256	`d0648399d738803a3be557bcc26beef7ba53341d2393277cde6cc82daa7c786e`

See more details on using hashes here.

Provenance

The following attestation bundles were made for awa_cli-0.6.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on hardbyte/awa

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: awa_cli-0.6.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Subject digest: d3d3961dd57c715d615b35f658d91389a20f96c5fd191c5426c1259d6f3d8bae
- Sigstore transparency entry: 2068034778
- Sigstore integration time: Jul 4, 2026
Source repository:
- Permalink: hardbyte/awa@671ca70e4ca38702fbe09a71653970f43ded0c8a
- Branch / Tag: refs/tags/v0.6.0
- Owner: https://github.com/hardbyte
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@671ca70e4ca38702fbe09a71653970f43ded0c8a
- Trigger Event: push

File details

Details for the file awa_cli-0.6.0-py3-none-macosx_11_0_arm64.whl.

File metadata

Download URL: awa_cli-0.6.0-py3-none-macosx_11_0_arm64.whl
Upload date: Jul 4, 2026
Size: 5.2 MB
Tags: Python 3, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for awa_cli-0.6.0-py3-none-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`b9c206e9e7b80f06b0fe1f28361d4fd030d8225a8e4b450c28b332c94ef51da7`
MD5	`c52e6a4398762c2e7ec13502f9ed1cfb`
BLAKE2b-256	`4c53d7da7648cf70fb4a5245a35d4a0fe06dd639b5a805610d98e6f307224197`

See more details on using hashes here.

Provenance

The following attestation bundles were made for awa_cli-0.6.0-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on hardbyte/awa

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: awa_cli-0.6.0-py3-none-macosx_11_0_arm64.whl
- Subject digest: b9c206e9e7b80f06b0fe1f28361d4fd030d8225a8e4b450c28b332c94ef51da7
- Sigstore transparency entry: 2068033742
- Sigstore integration time: Jul 4, 2026
Source repository:
- Permalink: hardbyte/awa@671ca70e4ca38702fbe09a71653970f43ded0c8a
- Branch / Tag: refs/tags/v0.6.0
- Owner: https://github.com/hardbyte
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@671ca70e4ca38702fbe09a71653970f43ded0c8a
- Trigger Event: push

File details

Details for the file awa_cli-0.6.0-py3-none-macosx_10_12_x86_64.whl.

File metadata

Download URL: awa_cli-0.6.0-py3-none-macosx_10_12_x86_64.whl
Upload date: Jul 4, 2026
Size: 5.4 MB
Tags: Python 3, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for awa_cli-0.6.0-py3-none-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`7cc112959b5b968c1dea2e7effcb51fd2bbcbb67c897c188c72c2bba6c4f1ebb`
MD5	`2b686020012d7ebef6b5881cbe9d6f87`
BLAKE2b-256	`cdb0d5148ab5e044ba6258b3015d71022d4201e2f6ae3ab59fa7806e83d81710`

See more details on using hashes here.

Provenance

The following attestation bundles were made for awa_cli-0.6.0-py3-none-macosx_10_12_x86_64.whl:

Publisher: release.yml on hardbyte/awa

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: awa_cli-0.6.0-py3-none-macosx_10_12_x86_64.whl
- Subject digest: 7cc112959b5b968c1dea2e7effcb51fd2bbcbb67c897c188c72c2bba6c4f1ebb
- Sigstore transparency entry: 2068034381
- Sigstore integration time: Jul 4, 2026
Source repository:
- Permalink: hardbyte/awa@671ca70e4ca38702fbe09a71653970f43ded0c8a
- Branch / Tag: refs/tags/v0.6.0
- Owner: https://github.com/hardbyte
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@671ca70e4ca38702fbe09a71653970f43ded0c8a
- Trigger Event: push

Release history Release notifications | RSS feed

0.6.5

Jul 29, 2026

0.6.4

Jul 22, 2026

0.6.3

Jul 15, 2026

0.6.2

Jul 13, 2026

0.6.1

Jul 7, 2026

This release

0.6.0

Jul 4, 2026

0.6.0rc4 pre-release

Jun 29, 2026

0.6.0rc3 pre-release

Jun 25, 2026

0.6.0rc2 pre-release

Jun 24, 2026

0.6.0rc1 pre-release

Jun 24, 2026

0.6.0b2 pre-release

Jun 10, 2026

0.6.0b1 pre-release

May 19, 2026

0.6.0a9 pre-release

May 8, 2026

0.6.0a8 pre-release

May 8, 2026

0.6.0a7 pre-release

May 7, 2026

0.6.0a6 pre-release

May 6, 2026

0.6.0a5 pre-release

May 4, 2026

0.6.0a4 pre-release

May 3, 2026

0.6.0a3 pre-release

May 2, 2026

0.6.0a2 pre-release

May 1, 2026

0.6.0a0 pre-release

Apr 30, 2026

0.5.7

May 7, 2026

0.5.6

Apr 27, 2026

0.5.5

Apr 20, 2026

0.5.5a0 pre-release

Apr 20, 2026

0.5.4a1 pre-release

Apr 17, 2026

0.5.4a0 pre-release

Apr 17, 2026

0.5.3

Apr 7, 2026

0.5.3a2 pre-release

Apr 7, 2026

0.5.3a1 pre-release

Apr 7, 2026

0.5.3a0 pre-release

Apr 6, 2026

0.5.2

Apr 1, 2026

0.5.1

Apr 1, 2026

0.5.1a3 pre-release

Mar 31, 2026

0.5.1a2 pre-release

Mar 31, 2026

0.5.1a1 pre-release

Mar 31, 2026

0.5.1a0 pre-release

Mar 31, 2026

0.5.0

Mar 30, 2026

0.5.0a2 pre-release

Mar 30, 2026

0.5.0a1 pre-release

Mar 29, 2026

0.5.0a0 pre-release

Mar 29, 2026

0.4.1

Mar 25, 2026

0.4.0

Mar 23, 2026

0.4.0a2 pre-release

Mar 23, 2026

0.4.0a1 pre-release

Mar 23, 2026

0.3.0

Mar 20, 2026

0.3.0a3 pre-release

Mar 20, 2026

awa-cli 0.6.0

awa-cli

Install

Quick start

Commands

Storage transition

Dead Letter Queue

Web UI

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Tags

Classifiers

Download files

Source Distributions

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed