CLI Reference

Every command-line tool that ships with VeltrixDB — the operator CLI, backup/restore tool, migration and chaos-testing utilities, load generator, and Kubernetes integrations — with real invocation syntax pulled from each tool's source.

All tools live under cmd/ in the VeltrixDB repository and build independently with go build -o <name> ./cmd/<dir>. None of them require the full server dependency tree at runtime; each talks to a running veltrixdb server over TCP and/or the admin HTTP API, except where noted as an offline/file-based tool.

veltrix — operator CLI

The primary day-to-day operator tool: cluster health, GC/compaction status, cache and WAL stats, live dashboards, and direct key read/write/delete via the text protocol. Think redis-cli merged with kubectl top.

go build -o veltrix ./cmd/veltrix

Global flags

Subcommands

Examples

veltrix status
veltrix top --watch 2
veltrix compaction --watch 5
veltrix cdc-tail --prefix orders/
veltrix metrics vlog_gc
veltrix put mykey "hello world"
veltrix get mykey
veltrix backup /mnt/backup/2026-07-05
veltrix checkpoint
veltrix --addr 10.0.0.5:2112 status

veltrixdb-backup — backup and restore tool

Offline/online backup and restore, including point-in-time recovery (PITR) and direct cloud upload/download to S3, GCS, or Azure. The engine must be stopped before restore or restore-pitr; full and incremental backups are safe to run against a live engine.

go build -o veltrixdb-backup ./cmd/backup

Local backup subcommands

Point-in-time recovery subcommands

Cloud subcommands

Shared cloud flags (from cloudFlags): --provider (s3|gcs|azure), --bucket, --prefix (default veltrixdb-backups), and provider-specific credentials: --region/--aws-access-key/--aws-secret-key for S3, --gcs-token/--gcs-cred-file for GCS, --azure-account/--azure-key for Azure. Each credential flag can instead be supplied via environment variable: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_SESSION_TOKEN, GOOGLE_APPLICATION_CREDENTIALS, GCS_ACCESS_TOKEN, AZURE_STORAGE_ACCOUNT, AZURE_STORAGE_KEY, AZURE_STORAGE_CONTAINER.

Examples

# Full local backup of a single-disk server
veltrixdb-backup full --data-dirs=/data --dest=/backup/full-2026-07-05

# Upload a local backup to S3
veltrixdb-backup upload \
    --src=/backup/full-2026-07-05 \
    --provider=s3 --bucket=my-veltrix-backups --region=us-east-1

# Full backup straight to GCS in one step
veltrixdb-backup full-cloud \
    --data-dirs=/data \
    --provider=gcs --bucket=my-bucket --gcs-cred-file=/sa.json

# Restore (engine must be stopped)
veltrixdb-backup restore --chain=/backup/full,/backup/inc1 --data-dirs=/data-new

# Inspect the PITR WAL archive
veltrixdb-backup archive-status --archive=/backup/wal-archive

# Point-in-time restore to an exact moment
veltrixdb-backup restore-pitr \
    --base-backup=/backup/full-2026-07-05 \
    --archive=/backup/wal-archive \
    --until=2026-07-05T14:30:00Z \
    --data=/data-new
# ...or exact to a single write:  --until=version:123456

See Backup & Restore for the full disaster-recovery workflow.

veltrix-admin — low-level administrative CLI

A separate, lower-level admin tool (cmd/admin) for offline VLog integrity checks and direct text-protocol operations that don't go through the HTTP admin API.

go build -o veltrix-admin ./cmd/admin

Examples

veltrix-admin scan --addr :9000
veltrix-admin stats --addr :9000 --user admin --password secret
veltrix-admin check --data-dirs /mnt/nvme0,/mnt/nvme1
veltrix-admin repair --addr :9000 --key corrupt-key-001 --user admin --password secret
veltrix-admin hash-password --user alice --password secret

veltrix-migrate — bulk data movement

Exports keys to JSONL, imports JSONL into a cluster, or copies directly between two clusters, using only the binary protocol plus /admin/stats for progress reporting.

go build -o veltrix-migrate ./cmd/veltrix-migrate

veltrix-migrate export --src 127.0.0.1:9000 --prefix orders/ > out.jsonl
veltrix-migrate import --dst replica:9000 < out.jsonl
veltrix-migrate migrate --src primary:9000 --dst replica:9000 --prefix orders/

veltrix-chaos — chaos-engineering harness

Inflicts controlled failures on running processes or Kubernetes pods to verify resilience claims: process kills, pause/resume (simulating GC pauses), network loss/delay, clock skew, and randomized soak testing.

go build -o veltrix-chaos ./cmd/veltrix-chaos

Target descriptor syntax: pid:NUMBER (local process by PID), process:NAME (local process by exec name, first match via pgrep -f), or k8s:NAMESPACE/POD (Kubernetes pod, operated on via kubectl).

veltrix-chaos kill process:veltrixdb
veltrix-chaos pause pid:4821 5s
veltrix-chaos network drop k8s:veltrixdb/veltrixdb-0 10
veltrix-chaos clock-skew k8s:veltrixdb/veltrixdb-1 +30
veltrix-chaos soak k8s:veltrixdb/veltrixdb-0 10m

All faults assume root or CAP_SYS_ADMIN on the target host. Compared to Jepsen, the source notes this trades formal rigor for zero JVM/Clojure dependency and trivial embedding in Go test suites via Inflict(...).

loadtest — concurrent load generator

A read/write load tester supporting single-op and batched (MPut/MGet) modes, with live throughput reporting and P50–P99.9 latency percentiles.

go run ./cmd/loadtest [flags]

Examples

# 30-second mixed 70% reads / 30% writes, 64 workers, 1M keyspace
go run ./cmd/loadtest --mode=mixed --read-ratio=0.7 --concurrency=64 --duration=30

# Write-only warmup then read-only benchmark
go run ./cmd/loadtest --mode=write --duration=10
go run ./cmd/loadtest --mode=read  --duration=30

# Batched writes via MPut-1024 (engages block packing)
go run ./cmd/loadtest --mode=write --batch-size=1024 \
                      --concurrency=8 --duration=30 --value-size=128

# Batched reads via MGet-256
go run ./cmd/loadtest --mode=read --batch-size=256 \
                      --concurrency=64 --duration=30

kubectl-veltrix — kubectl plugin

A dependency-free kubectl plugin that resolves a VeltrixDB pod by label selector, opens a kubectl port-forward to its admin port, and hits the HTTP admin API on localhost. No client-go or cobra dependency — it shells out to kubectl directly so auth and kubeconfig behavior always match the operator's normal workflow.

go build -o kubectl-veltrix ./cmd/kubectl-veltrix
# install: place the binary on PATH; kubectl auto-discovers it by the
# kubectl-PLUGIN naming convention.

Flags

Commands

kubectl veltrix stats
kubectl veltrix gc-status
kubectl veltrix quota-set tenant_42 5000 1000000
kubectl veltrix cdc tail --prefix orders/
kubectl veltrix -n veltrixdb-prod -l app.kubernetes.io/name=veltrixdb stats

repl-ship — cross-region replication shipper

Tails a local server's /admin/cdc stream and forwards each event to a remote VeltrixDB cluster's binary protocol — PUT events become a remote MultiPut, DEL events become a remote delete. Designed for asynchronous, eventually-consistent geo-replication, with exponential-backoff retries and a deadletter file for permanent failures.

go build -o repl-ship ./cmd/repl-ship

repl-ship --src http://primary:2112 \
          --src-token "$VELTRIX_ADMIN_TOKEN" \
          --dst-tcp replica.us-east:9000 \
          --batch 64 \
          --checkpoint /var/lib/repl-ship/ckpt

admin (cmd/admin)

This is the same binary documented above as veltrix-admin — its source lives at cmd/admin/main.go and it is conventionally built with the output name veltrix-admin. See that section for its full subcommand table.

Tool index