CLI
Create and inspect tasks, follow logs, and operate a cluster from the command line.
valka talks to any node of a cluster. Task and log commands use the gRPC API; cluster, worker
and queue commands use the REST API.
Installation
cargo install --path crates/valka-cliOr run it from the repository:
cargo run -p valka-cli -- --helpGlobal options
| Option | Environment | Default | Description |
|---|---|---|---|
--server | VALKA_SERVER | http://127.0.0.1:50051 | gRPC address of a node. Repeat it, or separate addresses with commas, to list several nodes: the CLI moves to the next one if a node does not answer |
--http | VALKA_HTTP | http://127.0.0.1:8989 | REST address of a node (cluster, worker and queue commands) |
--api-key | VALKA_API_KEY | - | API key, when the server sets VALKA_API_KEYS |
--admin-token | VALKA_ADMIN_TOKEN | - | Admin token, for cluster drain, cluster move, cluster unpin and queue partitions |
Tasks
Create a task
valka task create --queue emails --name send-welcome \
--input '{"to": "user@example.com"}' \
--priority 5 --max-retries 3 --timeout 300| Option | Default | Description |
|---|---|---|
--queue | required | Queue name |
--name | required | Task name |
--input | - | Input as JSON |
--priority | 0 | Higher runs first within a queue partition |
--max-retries | 3 | Attempts before the task is dead-lettered |
--timeout | 300 | Seconds an attempt may run |
--idempotency-key | generated | One task per key: running the command again returns the first task |
--scheduled-at | - | Run no earlier than this RFC 3339 time |
-q, --quiet | Print only the new task's id |
The CLI attaches a generated idempotency key when you give none, so a create retried after a node failure never makes a second task.
Get a task
valka task get 01912345-6789-7abc-def0-123456789abcList tasks
valka task list --queue emails --status RUNNING --limit 20--status is one of PENDING, RUNNING, COMPLETED, FAILED, RETRY, DEAD_LETTER or
CANCELLED.
Cancel a task
valka task cancel 01912345-6789-7abc-def0-123456789abcLogs
Follow a run's logs
valka logs tail <TASK_RUN_ID>Prints the run's log lines so far, then new ones as they arrive. Stop with Ctrl-C. Run ids are on
the task's page in the dashboard, or from GET /api/v1/tasks/{id}/runs.
Workers
valka worker listThe workers connected to every node, with their node, queues, concurrency and active tasks.
Cluster
valka cluster status # health, nodes, shards owned, pending and running tasks
valka cluster members # every node's lease: incarnation, status, lease age, eligibilityThese need the admin token:
valka cluster drain valka-2 # hand valka-2's shards to the others, then stop it
valka cluster move 1731 --to valka-3 # pin shard 1731 to valka-3
valka cluster unpin 1731 # back to automatic placementQueues
valka queue list # partitions per queue, and partitions still draining
valka queue partitions emails 32 # change a queue's partition count (admin token)Examples
A full round trip
export VALKA_API_KEY=... # if the server requires one
TASK_ID=$(valka task create --queue emails --name send-email --input '{"to":"a@b.c"}' -q)
valka task get "$TASK_ID"
valka task list --status RUNNING
valka task cancel "$TASK_ID"Watching a cluster
export VALKA_SERVER=http://valka-1:50051,http://valka-2:50051,http://valka-3:50051
export VALKA_HTTP=http://valka-1:8989
valka cluster status
valka task list --status DEAD_LETTER