CLI Reference
The flexiq command-line interface — worker, dashboard, info, pause, resume, scaler, autoscale, resources, reload.
The flexiq command-line interface — worker, dashboard, info, pause, resume, scaler, autoscale, resources, reload.
flexiq provides a command-line interface for running workers and inspecting queue state.
The CLI is installed automatically with the package:
pip install flexiqThe flexiq command becomes available in your PATH.
flexiq workerStart a worker process that consumes and executes tasks.
flexiq worker --app <module:attribute> [--queues <queue1,queue2,...>]| Flag | Required | Description |
|---|---|---|
--app | Yes | Python path to the Queue instance in module:attribute format |
--queues | No | Comma-separated list of queues to process. Default: all registered queues |
--pool | No | Worker pool type: thread (default) or prefork |
Examples:
# Start a worker using the queue defined in myapp/tasks.py
flexiq worker --app myapp.tasks:queue
# Only process the "emails" and "reports" queues
flexiq worker --app myapp.tasks:queue --queues emails,reports
# Use a nested module path
flexiq worker --app myproject.workers.tasks:task_queue
# Use the prefork pool
flexiq worker --app myapp.tasks:queue --pool preforkThe worker blocks until interrupted with Ctrl+C. It performs a graceful
shutdown — in-flight tasks are allowed to complete before the process exits.
flexiq dashboardStart the web dashboard (SPA + REST API) for the queue.
flexiq dashboard --app <module:attribute> [--host <addr>] [--port <port>] [--auth] [--insecure-cookies]| Flag | Default | Description |
|---|---|---|
--app | — | Python path to the Queue instance |
--host | 127.0.0.1 | Bind address |
--port | 8080 | Bind port |
--auth | False | Enable session authentication (login/setup, CSRF, roles); off by default |
--insecure-cookies | False | Drop the Secure flag on session cookies (local HTTP dev only) |
Example:
flexiq dashboard --app myapp.tasks:queue --port 8080See the Dashboard guide for authentication and deployment.
flexiq pause / flexiq resumePause or resume a named queue. A paused queue stops dequeuing new jobs; in-flight jobs still run to completion.
flexiq pause --app <module:attribute> <queue_name>
flexiq resume --app <module:attribute> <queue_name>| Flag / Arg | Required | Description |
|---|---|---|
--app | Yes | Python path to the Queue instance |
queue_name | Yes | Name of the queue to pause or resume |
Example:
flexiq pause --app myapp.tasks:queue emails
flexiq resume --app myapp.tasks:queue emailsflexiq infoDisplay queue statistics.
flexiq info --app <module:attribute> [--watch]| Flag | Required | Description |
|---|---|---|
--app | Yes | Python path to the Queue instance |
--watch | No | Continuously refresh stats every 2 seconds |
Examples:
# Show stats once
flexiq info --app myapp.tasks:queueOutput:
flexiq queue statistics
------------------------------
pending 12
running 4
completed 1847
failed 0
dead 2
cancelled 0
------------------------------
total 1865
# Live monitoring with throughput
flexiq info --app myapp.tasks:queue --watchOutput (refreshes every 2s):
flexiq queue statistics
------------------------------
pending 3
running 8
completed 2104
failed 0
dead 2
cancelled 0
------------------------------
total 2117
throughput 12.5 jobs/s
Refreshing every 2s... (Ctrl+C to stop)
The --app flag uses module:attribute format:
myapp.tasks:queue
│ │
│ └── attribute name (the Queue variable)
└── Python module path (dotted, importable)
The module must be importable from the current working directory. If your
module is in a package, make sure the package is installed or the parent
directory is in PYTHONPATH.
Common patterns:
| App structure | --app value |
|---|---|
tasks.py with queue = Queue() | tasks:queue |
myapp/tasks.py with queue = Queue() | myapp.tasks:queue |
src/workers/q.py with app = Queue() | src.workers.q:app |
flexiq scalerStart a lightweight KEDA metrics server.
flexiq scaler --app <module:attribute> [--host <addr>] [--port <port>] [--target-queue-depth <n>]| Flag | Default | Description |
|---|---|---|
--app | — | Python path to the Queue instance |
--host | 0.0.0.0 | Bind address |
--port | 9091 | Bind port |
--target-queue-depth | 10 | Scaling target hint returned to KEDA in /api/scaler responses |
The server exposes three routes:
| Route | Description |
|---|---|
GET /api/scaler | Queue depth and target for KEDA metrics-api trigger. Add ?queue=<name> to filter. |
GET /metrics | Prometheus text format (requires prometheus-client). |
GET /health | Liveness probe — always returns {"status": "ok"}. |
Example:
flexiq scaler --app myapp:queue --port 9091 --target-queue-depth 5See the KEDA Integration guide for Kubernetes deploy templates.
flexiq autoscaleStart a bare-metal autoscaler that spawns and drains worker processes based on queue depth and worker utilisation.
flexiq autoscale --app <module:attribute> [options]| Flag | Default | Description |
|---|---|---|
--app | — | Python path to the Queue instance |
--min-workers | 1 | Minimum worker count |
--max-workers | 10 | Maximum worker count |
--target-queue-depth | 15 | Target queue depth per worker |
--target-utilisation | 0.75 | Target worker utilisation (0.0–1.0) |
--scale-up-window | 0 | Seconds of sustained demand before scaling up |
--scale-down-window | 300 | Seconds of low demand before scaling down |
--tolerance | 0.1 | Scaling tolerance band |
--poll-interval | 5 | Seconds between scaling decisions |
--drain-timeout | 30 | Seconds to wait for in-flight jobs during scale-down |
--threads-per-worker | 4 | Worker threads per spawned process |
Example:
flexiq autoscale --app myapp.tasks:queue --min-workers 2 --max-workers 20See the Autoscaler guide for deployment patterns and tuning advice.
flexiq resourcesShow the status of every registered resource — scope, health, init time, recreation count, and dependencies.
flexiq resources --app <module:attribute>| Flag | Required | Description |
|---|---|---|
--app | Yes | Python path to the Queue instance |
See the Resource System guide for background.
flexiq reloadSend SIGHUP to a running worker process to hot-reload resources without
restarting the worker.
flexiq reload --pid <pid> [--resource <name>]| Flag | Required | Description |
|---|---|---|
--pid | Yes | PID of the running worker process |
--resource | No | Reload only this resource (default: all reloadable resources) |
Example:
flexiq reload --pid 12345
flexiq reload --pid 12345 --resource db_pool| Error | Cause |
|---|---|
--app must be in 'module:attribute' format | Missing : separator |
could not import module '...' | Module not found or import error |
module '...' has no attribute '...' | Attribute doesn't exist on the module |
'...' is not a Queue instance | The attribute exists but isn't a Queue |