absurdctl¶

absurdctl is a Python CLI tool for managing Absurd schemas, queues, tasks, and events. It talks directly to Postgres using standard PG* environment variables.

Installation¶

absurdctl is available from GitHub Releases. Download it and place it on your PATH. It requires Python 3 and psql.

# Set your database connection
export PGDATABASE="postgresql://user:pass@localhost:5432/mydb"

You can also pass connection details as flags (-d, -h, -p, -U) to each command.

Connection Options¶

All commands accept these flags:

Using a full URI is the simplest approach:

export PGDATABASE="postgresql://user:pass@localhost:5432/mydb"

Schema Management¶

init¶

Apply the Absurd schema (absurd.sql) to the database. Safe to run on a fresh database.

absurdctl init
absurdctl init -d mydb

schema-version¶

Display the currently installed schema version.

absurdctl schema-version

migrate¶

Apply incremental migrations to bring the schema up to the target version. Migrations are bundled into built copies of absurdctl (via scripts/build-absurdctl) or fetched from GitHub.

absurdctl migrate
absurdctl migrate -d mydb
absurdctl migrate --from 0.1.0 --to main --dump-sql > absurd-migrations.sql

Options:

Queue Management¶

create-queue¶

Create a new queue. This creates the per-queue tables (t_, r_, c_, e_, w_).

absurdctl create-queue default
absurdctl create-queue emails -d mydb

drop-queue¶

Drop a queue and all its data. Requires --yes for confirmation.

absurdctl drop-queue old-queue --yes

list-queues¶

List all existing queues.

absurdctl list-queues

Task Operations¶

spawn-task¶

Enqueue a new task. Parameters are passed with -P key=value (strings) or -P key:=json (typed JSON).

absurdctl spawn-task my-task -P name=Alice -P count:=42
absurdctl spawn-task --queue reports generate-report -P month=january

Options:

list-tasks¶

List tasks with optional filtering.

absurdctl list-tasks
absurdctl list-tasks --queue=default --status=failed
absurdctl list-tasks --status=running --limit=20

Options:

dump-task¶

Show detailed information about a task or run, including checkpoints.

absurdctl dump-task --task-id=019a32d3-8425-7ae2-a5af-2f17a6707666
absurdctl dump-task --run-id=019a32d3-8425-7ae2-a5af-2f17a6707667

cancel-task¶

Cancel a running or pending task.

absurdctl cancel-task 019a32d3-8425-7ae2-a5af-2f17a6707666
absurdctl cancel-task 019a32d3-8425-7ae2-a5af-2f17a6707666 --queue=emails

retry-task¶

Retry a failed task, optionally increasing the attempt limit.

absurdctl retry-task 019a32d3-8425-7ae2-a5af-2f17a6707666
absurdctl retry-task 019a32d3-8425-7ae2-a5af-2f17a6707666 --max-attempts 10

Events¶

emit-event¶

Emit an event to wake tasks waiting for it. Parameters become the event payload.

absurdctl emit-event order.completed -P orderId=123
absurdctl emit-event --queue=orders shipment.packed -P tracking:='"XYZ"'

Cleanup¶

cleanup¶

Delete old completed, failed, or cancelled tasks and events. Takes a queue name and a TTL in days.

absurdctl cleanup default 7     # delete data older than 7 days
absurdctl cleanup emails 30     # 30-day retention

Agent Help¶

agent-help¶

Print guidance tailored for AI coding agents. Append it to your AGENTS.md or CLAUDE.md:

absurdctl agent-help >> AGENTS.md

Bundled Builds¶

For deployment, scripts/build-absurdctl creates a self-contained copy with the schema SQL and migrations embedded:

make build-absurdctl

The bundled version works without network access for init and migrate.

Examples¶

# Full setup from scratch
export PGDATABASE="postgresql://user:pass@localhost:5432/mydb"
absurdctl init
absurdctl create-queue default
absurdctl spawn-task hello-world -P name=Alice
absurdctl list-tasks --status=pending
absurdctl dump-task --task-id=<id>
absurdctl cleanup default 7