CLI Reference¶

The runqy server includes a comprehensive command-line interface for managing queues, tasks, workers, and configurations. The CLI can operate locally (direct database access) or remotely (via HTTP API).

Installation¶

Build the CLI from source:

cd runqy/app
go build -o runqy .

Command Overview¶

Command	Description
`runqy`	Start the HTTP server (default, same as `runqy serve`)
`runqy serve`	Start the HTTP server
`runqy queue`	Queue management commands
`runqy task`	Task management commands
`runqy worker`	Worker management commands
`runqy config`	Configuration management commands
`runqy vault`	Vault management commands (secrets)
`runqy autoscale`	GPU autoscaling: instances, protection, providers
`runqy alerts`	Email alerts: status and test email
`runqy login`	Save server credentials for remote mode
`runqy logout`	Remove saved credentials
`runqy auth`	Authentication management (status, list, switch)

Server Commands¶

Start the Server¶

# Start with defaults
runqy serve

# Or simply (serve is the default command)
runqy

# Start with custom config directory
runqy serve --config ./my-deployment

# Start with git-based config and auto-reload
runqy serve --config-repo https://github.com/org/configs.git --watch

# Start without monitoring dashboard (API only)
runqy serve --no-ui

Serve Flags:

Flag	Description	Default
`--config`	Path to queue workers config directory	`QUEUE_WORKERS_DIR` env
`--watch`	Enable file/git watching for config auto-reload	`false`
`--no-ui`	Disable the monitoring web dashboard	`false`
`--config-repo`	GitHub repo URL for configs	-
`--config-branch`	Git branch	`main`
`--config-path`	Path within repo to YAML files	-
`--clone-dir`	Directory to clone repo into	-
`--watch-interval`	Git polling interval in seconds	-

Queue Commands¶

List Queues¶

runqy queue list

Output:

QUEUE              PENDING  ACTIVE  SCHEDULED  RETRY  ARCHIVED  COMPLETED  PAUSED
inference.high     5        2       0          1      0         150        no
inference.low      12       0       3          0      0         89         no

Inspect Queue¶

runqy queue inspect inference.high

Shows detailed queue information including status, pause state, memory usage, and task counts.

Pause/Unpause Queue¶

# Pause a queue (stops processing new tasks)
runqy queue pause inference.high

# Resume a paused queue
runqy queue unpause inference.high

Task Commands¶

Enqueue a Task¶

# Enqueue a task with JSON payload
runqy task enqueue --queue inference.high --payload '{"prompt":"Hello world","width":1024}'

# Short flags
runqy task enqueue -q inference.high -p '{"msg":"test"}'

# With custom timeout (seconds)
runqy task enqueue -q inference.high -p '{"data":"value"}' --timeout 300

Enqueue Flags:

Flag	Description	Default
`-q, --queue`	Queue name (required)	-
`-p, --payload`	JSON payload	`{}`
`-t, --timeout`	Max execution time per attempt, in seconds. `0` uses the queue's `active_timeout`	`0`

List Tasks¶

# List pending tasks in a queue
runqy task list inference.high

# List tasks by state
runqy task list inference.high --state pending
runqy task list inference.high --state active
runqy task list inference.high --state scheduled
runqy task list inference.high --state retry
runqy task list inference.high --state archived
runqy task list inference.high --state completed

# Limit number of results
runqy task list inference.high --state pending --limit 20

Get Task Details¶

runqy task get inference.high abc123-task-id

Output:

Task ID:     abc123-task-id
Type:        task
Queue:       inference.high
State:       completed
Max Retry:   3
Retried:     0
Timeout:     10m0s
...

Cancel and Delete Tasks¶

# Cancel a running task
runqy task cancel abc123-task-id

# Delete a task from a queue
runqy task delete inference.high abc123-task-id

Worker Commands¶

List Workers¶

runqy worker list

Output:

WORKER_ID                              STATUS  QUEUES          CONCURRENCY  LAST_BEAT  STALE
worker-abc123-def456                   ready   inference.high  1            5s         no
worker-xyz789-uvw012                   ready   inference.low   1            3s         no

Get Worker Info¶

runqy worker info worker-abc123-def456

Output:

Worker ID:   worker-abc123-def456
Status:      ready
Queues:      inference.high
Concurrency: 1
Started At:  2024-01-15 10:30:00
Last Beat:   2024-01-15 10:35:45 (5s ago)

Config Commands¶

List Queue Configurations¶

runqy config list

Output:

NAME              PRIORITY  PROVIDER  MODE          GIT_URL
inference.high    10        worker    long_running  https://github.com/org/worker.git
inference.low     5         worker    long_running  https://github.com/org/worker.git
simple.default    1         worker    one_shot      https://github.com/org/simple.git

Reload Configurations¶

# Reload configs from default directory (QUEUE_WORKERS_DIR)
runqy config reload

# Reload from a specific directory
runqy config reload --dir ./my-deployment

Validate Configuration Files¶

# Validate YAML files without loading into database
runqy config validate

# Validate from a specific directory
runqy config validate --dir ./my-deployment

Note

config validate is local-only and does not work in remote mode.

Create Queue Configuration¶

# From YAML file
runqy config create -f ./my-queue.yaml

# Inline parameters
runqy config create --name myqueue --priority 5 \
  --git-url https://github.com/org/repo.git \
  --startup-cmd "python main.py"

# Update existing queue (use --force)
runqy config create -f ./queue.yaml --force

Create Flags:

Flag	Description	Default
`-f, --file`	YAML config file path	-
`--name`	Queue name	-
`--priority`	Queue priority	`1`
`--git-url`	Git repository URL	-
`--branch`	Git branch	`main`
`--startup-cmd`	Startup command	-
`--mode`	Mode: `long_running` or `one_shot`	`long_running`
`--code-path`	Path within repo to the code	-
`--force`	Update existing queue if it already exists	`false`

Remove Queue Configuration¶

runqy config remove myqueue

# Or with flag
runqy config remove --name myqueue

Vault Commands¶

Vaults store encrypted secrets that are injected into workers as environment variables.

Prerequisite

The vaults feature requires the RUNQY_VAULT_MASTER_KEY environment variable to be set on the server.

List Vaults¶

runqy vault list

Output:

NAME         DESCRIPTION                    ENTRIES
api-keys     API keys for external services 3
credentials  Database credentials           2

Create a Vault¶

# Create with description
runqy vault create api-keys -d "API keys for external services"

# Create without description
runqy vault create my-secrets

Show Vault Details¶

runqy vault show api-keys

Output:

Vault: api-keys
Description: API keys for external services
Created: 2024-01-15T10:30:00Z
Updated: 2024-01-15T12:45:00Z

Entries (3):
KEY              VALUE           SECRET
OPENAI_API_KEY   sk****yz        yes
HF_TOKEN         hf****ab        yes
DEBUG_MODE       true            no

Secret values are masked in the output for security.

Delete a Vault¶

# With confirmation prompt
runqy vault delete api-keys

# Skip confirmation
runqy vault delete api-keys --force

Set a Vault Entry¶

# Set a secret entry (default)
runqy vault set api-keys OPENAI_API_KEY sk-your-key-here

# Set a non-secret entry (visible in API responses)
runqy vault set api-keys DEBUG_MODE true --no-secret

Set Flags:

Flag	Description	Default
`--no-secret`	Store as non-secret (visible in API)	`false`

Get a Vault Entry¶

runqy vault get api-keys OPENAI_API_KEY

Output:

sk-your-actual-key-here

Local Only

The vault get command only works in local mode for security reasons. It returns the decrypted value.

Remove a Vault Entry¶

runqy vault unset api-keys OPENAI_API_KEY

List Vault Entries¶

runqy vault entries api-keys

Output:

KEY              VALUE           SECRET  UPDATED
OPENAI_API_KEY   sk****yz        yes     2024-01-15T12:45:00Z
HF_TOKEN         hf****ab        yes     2024-01-15T10:30:00Z
DEBUG_MODE       true            no      2024-01-15T11:00:00Z

Autoscale Commands¶

Manage GPU autoscaling. Per-queue rules live in the queue configuration; these commands cover live instances and the provider registry.

Instance Status¶

runqy autoscale status

INSTANCE ID   QUEUE      PROVIDER    STATUS   WORKER     PROTECTED  COST
as-231d…      inference  gpu-runpod  running  a1b2c3:7   false      $0.4120

Total accumulated cost: $0.4120

Protect an Instance¶

runqy autoscale protect as-231d7097-…     # never scaled down
runqy autoscale unprotect as-231d7097-…

Providers¶

Provider commands need RUNQY_VAULT_MASTER_KEY on the server (credentials are encrypted).

runqy autoscale provider-types                     # mock, runpod, vastai
runqy autoscale providers list
runqy autoscale providers show gpu-runpod          # secrets masked

# Create (config as literal JSON or @file)
runqy autoscale providers create my-mock --type mock
runqy autoscale providers create gpu-runpod --type runpod --config @runpod.json
runqy autoscale providers create gpu-vast --type vastai --config '{"api_key":"xxx","gpu_name":"RTX_4090"}' --disabled

# Update: only what you pass changes
runqy autoscale providers update gpu-runpod --config @runpod.json
runqy autoscale providers update gpu-runpod --disable    # keeps the stored config
runqy autoscale providers update gpu-runpod --enable

runqy autoscale providers delete gpu-vast --force

Alerts Commands¶

Inspect email alerts and test delivery. Settings are configured in YAML (top-level alerts block) or in the dashboard.

Alert Status¶

runqy alerts status
runqy alerts status --history 100

Alerting: enabled
Last evaluation: 2026-10-14T11:58:21+02:00

STATE   QUEUE      RULE        SINCE  DETAILS
FIRING  inference  no_workers  2m10s  no live worker is serving the queue (3 job(s) pending)

Recent notifications:
TIME              STATUS  QUEUE      RULE        DETAILS
2026-10-14 11:58  FIRING  inference  no_workers  no live worker is serving the queue (3 job(s) pending)

Flag	Default	Description
`--history`	`20`	Number of recent notifications to show

Send a Test Email¶

runqy alerts test

Sends a test email to the configured recipients with the saved settings, and prints the delivery error if it fails.

Control Commands¶

Send commands to workers over the Redis control channel. See the Worker Control guide.

runqy control drain --target inference          # stop taking new tasks
runqy control resume --target inference
runqy control code-update --target inference    # update code, deps, restart the process
runqy control worker-update --version 0.4.1     # install a worker release in place
runqy control config-reload --target inference  # run the task's @reload handler

Sent drain to queue inference (id 2223310d948b29a8, 1 receiver(s)).
Check the outcome with: runqy worker info <worker_id>

Flag	Description
`-t`, `--target`	Worker id or queue name (default: every worker)
`--version`	Release to install (`worker-update` only, required)
`--timeout`	How long to wait for tasks in flight, e.g. `10m` (code and worker updates default to `30m`)

runqy worker info <id> shows the worker version, the held queues and the last command:

Version:     0.4.0
Held:        inference (not taking new tasks)
Last cmd:    code_update done: updated inference main (process restarted) (5s ago)

Remote Mode¶

The CLI can operate in two modes:

Local mode (default): Connects directly to Redis/PostgreSQL
Remote mode: Connects to a runqy server via HTTP API

Use remote mode to manage a runqy server from a different machine.

Usage¶

# Remote mode - specify server URL and API key
runqy --server https://runqy.example.com:3000 --api-key YOUR_API_KEY queue list

# Short flags
runqy -s https://runqy.example.com:3000 -k YOUR_API_KEY queue list

# API key can also be set via environment variable
export RUNQY_API_KEY=YOUR_API_KEY
runqy -s https://runqy.example.com:3000 queue list

Remote Mode Examples¶

# List queues on remote server
runqy -s https://server:3000 -k API_KEY queue list

# Enqueue a task on remote server
runqy -s https://server:3000 -k API_KEY task enqueue -q inference.high -p '{"msg":"hello"}'

# List workers on remote server
runqy -s https://server:3000 -k API_KEY worker list

# Trigger config reload on remote server
runqy -s https://server:3000 -k API_KEY config reload

Remote Mode Support¶

Command	Remote Support	Notes
`queue list/inspect/pause/unpause`	Yes	Full support
`task enqueue/list/get/cancel/delete`	Yes	Full support
`worker list/info`	Yes	Full support
`config list/reload/create/remove`	Yes	Full support
`config validate`	No	Local-only (validates local YAML files)
`vault list/create/show/delete`	Yes	Full support
`vault set/unset/entries`	Yes	Full support
`vault get`	No	Local-only (returns decrypted secrets)
`autoscale status/protect/unprotect`	Yes	Full support
`autoscale providers ...`	Yes	Full support
`alerts status/test`	Yes	Full support
`serve`	No	Server command, not applicable

Authentication Persistence¶

Save server credentials so you don't need to specify --server and --api-key for every command.

# Save credentials for a server (saved as "default" profile)
runqy login -s https://production.example.com:3000 -k prod-api-key

# Save with a custom profile name (it becomes the active profile)
runqy login -s https://staging.example.com:3000 -k staging-key --name staging

# Save a profile without switching to it
runqy login -s https://staging.example.com:3000 -k staging-key --name staging --no-switch

# API key can be prompted interactively
runqy login -s https://server:3000
# API Key: <enter key>

Credentials are stored in ~/.runqy/credentials.json with restricted permissions (0600).

login makes the profile it saves the active one and prints it (Active profile: "staging"), so the next commands go to the server you just logged into. Use --no-switch to keep the current profile, and runqy auth switch <name> to change it later.

Using Saved Credentials¶

After logging in, commands work without flags:

# Before (verbose)
runqy --server https://server:3000 --api-key KEY queue list

# After login (simple)
runqy queue list
runqy task enqueue -q myqueue -p '{"msg":"hello"}'
runqy worker list

Manage Multiple Servers¶

# List all saved servers
runqy auth list

Output:

NAME     URL                                    CURRENT
default  https://production.example.com:3000   *
staging  https://staging.example.com:3000

# Show current connection
runqy auth status

Output:

Current server: default
URL: https://production.example.com:3000
API Key: prod...key

# Switch to different server
runqy auth switch staging
# Switched to "staging"

Logout¶

# Remove current profile
runqy logout

# Remove specific profile
runqy logout --name staging

# Remove all saved credentials
runqy logout --all

Credential Priority¶

Credentials are resolved in this order (highest to lowest):

Command-line flags (--server, --api-key)
Environment variables (RUNQY_SERVER, RUNQY_API_KEY)
Saved credentials (~/.runqy/credentials.json)
Local mode (direct Redis/PostgreSQL access)

Global Flags¶

These flags are available for all commands:

Flag	Description
`-s, --server`	Remote server URL for CLI-over-HTTP mode
`-k, --api-key`	API key for authentication (or set `RUNQY_API_KEY` env var)
`--redis-uri`	Redis URI (overrides `REDIS_HOST`/`REDIS_PORT`)
`-v, --version`	Print version information
`-h, --help`	Help for the command

Shell Completion¶

Generate shell completion scripts for your shell:

BashZshFishPowerShell

runqy completion bash > /etc/bash_completion.d/runqy

runqy completion zsh > "${fpath[1]}/_runqy"

runqy completion fish > ~/.config/fish/completions/runqy.fish

runqy completion powershell > runqy.ps1

CLI Reference¶

Installation¶

Command Overview¶

Server Commands¶

Start the Server¶

Queue Commands¶

List Queues¶

Inspect Queue¶

Pause/Unpause Queue¶

Task Commands¶

Enqueue a Task¶

List Tasks¶

Get Task Details¶

Cancel and Delete Tasks¶

Worker Commands¶

List Workers¶

Get Worker Info¶

Config Commands¶

List Queue Configurations¶

Reload Configurations¶

Validate Configuration Files¶

Create Queue Configuration¶

Remove Queue Configuration¶

Vault Commands¶

List Vaults¶

Create a Vault¶

Show Vault Details¶

Delete a Vault¶

Set a Vault Entry¶

Get a Vault Entry¶

Remove a Vault Entry¶

List Vault Entries¶

Autoscale Commands¶

Instance Status¶

Protect an Instance¶

Providers¶

Alerts Commands¶

Alert Status¶

Send a Test Email¶

Control Commands¶

Remote Mode¶

Usage¶

Remote Mode Examples¶

Remote Mode Support¶

Authentication Persistence¶

Login and Save Credentials¶

Using Saved Credentials¶

Manage Multiple Servers¶

Logout¶

Credential Priority¶

Global Flags¶

Shell Completion¶