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

The usage is veltrix [flags] COMMAND [args], and the flags must come before the command: the CLI uses Go's flag package, which stops parsing at the first non-flag argument, so anything after the command is treated as an argument and a flag there is silently ignored. veltrix --watch 5 top refreshes every 5 s; veltrix top --watch 5 runs at the 2 s default. (The v1.12 CLI's own built-in help still shows the second form in its examples.) Fixed in v1.14 flags work before or after the command, so veltrix top --watch 5 and veltrix --watch 5 top are the same; put -- before an argument that starts with - (veltrix put k -- -1).

Subcommands

Fixed in v1.14 cache, compaction, status and top read the untagged CacheStats / VLogStats fields, quotas reads QuotaSnapshot, traces reads start_unix_ns, and a text-protocol ERR … from get is shown as-is. On v1.13 and earlier some of these fields print empty or zero; use --json or curl on the endpoint.

Examples

veltrix status
veltrix --watch 5 top
veltrix --watch 5 compaction
veltrix --json status
veltrix --prefix orders/ cdc-tail
veltrix metrics vlog_gc
veltrix put mykey "hello world"
veltrix get mykey
veltrix backup /mnt/backup/2026-07-05
veltrix cluster members                       # next release (main after v1.16)
veltrix cluster add-node n4@10.0.0.14:9000
veltrix cluster remove-node n2
veltrix checkpoint
veltrix --addr 127.0.0.1:2112 --tcp 127.0.0.1:9000 status

veltrixdb-backup — backup and restore tool

Offline backup and restore, including point-in-time recovery (PITR) and direct cloud upload/download to S3, GCS, or Azure. Every command takes its flags after the subcommand (veltrixdb-backup full --data-dirs=... --dest=...); veltrixdb-backup <command> -help lists them.

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

Local backup subcommands

Point-in-time recovery subcommands

Cloud subcommands

Shared cloud flags (from cloudFlags, on upload, download, list-cloud and full-cloud): --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

# Running server: let the server write the backup (loopback, or add the admin token)
veltrix backup /backup/full-2026-07-05

# Stopped server: full local backup of its data dir
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 (server stopped)
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

# Unbatched reads against the C++ front-end (server started with --net=cpp)
go run ./cmd/loadtest --mode=read --proto=binary --concurrency=64 --duration=30

veltrix-repair — offline value-metadata repair

New in v1.3 Offline repair for nodes that ran a build predating the value-transform WAL fix with compression (zstd is the default) or --encrypt-at-rest, and were restarted since writing data. On such nodes reads after a clean restart can return the raw compressed/encrypted blob, and reads after a crash fail with a CRC32C mismatch. The VLog bytes are intact; the tool rebuilds the lost metadata in place and rewrites the WAL as a corrected (binary) checkpoint on exit. The server must be stopped.

# 1. Always scan first (read-only)
veltrix-repair --data-dirs /mnt/nvme0,/mnt/nvme1 --scan

# 2. Repair (each wal.log is backed up first)
veltrix-repair --data-dirs /mnt/nvme0,/mnt/nvme1 --repair

Exit codes: 0 nothing to do / repaired, 1 scan found work, 2 entries could not be resolved, 3 error.

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

As with veltrix, flags go before the command (kubectl veltrix -n prod --prefix=orders/ cdc-tail); after it they are ignored. The v1.12 plugin sends no admin token: through the port-forward its requests arrive from loopback, which is enough for a server without -admin-token and gets 401 from one with it. Fixed in v1.14 flags also work after the command, --admin-token / VELTRIX_ADMIN_TOKEN reaches guarded servers, and HTTP errors exit 1.

Commands

kubectl veltrix stats
kubectl veltrix gc-status
kubectl veltrix quota-set tenant_42 5000 1000000
kubectl veltrix --prefix=orders/ cdc-tail
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 — each PUT event becomes a binary PUT and each DEL event a binary DEL, sent one request at a time (--batch only sets how many events are buffered per flush). Flags are listed on Replication & CDC. 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