valka

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-cli

Or run it from the repository:

cargo run -p valka-cli -- --help

Global options

OptionEnvironmentDefaultDescription
--serverVALKA_SERVERhttp://127.0.0.1:50051gRPC 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
--httpVALKA_HTTPhttp://127.0.0.1:8989REST address of a node (cluster, worker and queue commands)
--api-keyVALKA_API_KEY-API key, when the server sets VALKA_API_KEYS
--admin-tokenVALKA_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
OptionDefaultDescription
--queuerequiredQueue name
--namerequiredTask name
--input-Input as JSON
--priority0Higher runs first within a queue partition
--max-retries3Attempts before the task is dead-lettered
--timeout300Seconds an attempt may run
--idempotency-keygeneratedOne task per key: running the command again returns the first task
--scheduled-at-Run no earlier than this RFC 3339 time
-q, --quietPrint 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-123456789abc

List 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-123456789abc

Logs

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 list

The 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, eligibility

These 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 placement

Queues

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

On this page