Command Reference

Vaylix commands are parsed by the shared command crate before being encoded into transport requests. The client keeps help, exit, and quit local; server-recognized commands go over the framed binary transport.

Connection and Diagnostics

AUTH

auth <username> <password>

Authenticates the current connection when auth is enabled.

Example:

auth vaylix vaylix

PING

ping [message]

Returns PONG or the supplied message.

Example:

ping healthcheck

INFO

info

Returns deterministic key/value fields with section prefixes such as server.*, transport.*, persistence.*, security.*, runtime.*, and metrics.*.

METRICS

metrics
metrics prom

metrics returns OTel-aligned key/value metrics like vaylix.server.request.count. metrics prom returns the same contract in Prometheus text exposition form.

Example:

metrics prom

Key Value Commands

Keys are UTF-8 strings. Values are opaque bytes. CLI examples below use text input, which is sent as UTF-8, but the transport and SDK also support arbitrary binary payloads.

GET

get <key>

Reads a value. Missing keys return NOT_FOUND.

Example:

get app:mode

SET

set <key> <value> [nx|xx] [if version <version>] [ex <seconds>|px <millis>] [keepttl] [get]

Writes a value with optional existence conditions, version-based compare-and-set, expiration, TTL preservation, and previous-value return.

Example:

set app:mode production ex 60
set profile:blob updated if version 7

SETNX

setnx <key> <value>

Writes only when the key does not already exist.

GETDEL

getdel <key>

Reads and deletes a key atomically.

GETEX

getex <key> [ex <seconds>|px <millis>|persist]

Reads a key and updates or clears its expiration.

MGET

mget <key> [key ...]

Reads multiple keys in one request.

Example:

mget app:mode app:region

MSET

mset <key> <value> [key value ...]

Writes multiple key/value pairs in one request.

DEL / DELETE

del <key> [key ...]
delete <key> [key ...]

Deletes one or more keys and returns the deleted count.

EXISTS

exists <key>

Returns whether the key exists.

Numeric Operations

Numeric commands interpret the stored value as a signed integer encoded in UTF-8 text.

INCR

incr <key>

Increments a numeric string and returns the new value.

DECR

decr <key>

Decrements a numeric string and returns the new value.

If the current value is not parseable as an integer, the server returns a structured error.

Expiration and Key Lifecycle

EXPIRE

expire <key> <seconds>

Sets a TTL in whole seconds.

TTL

ttl <key>

Returns the remaining TTL using the current integer TTL convention.

PERSIST

persist <key>

Removes a key expiration if present.

Expired keys are purged on normal command paths, during background sweeps, and during snapshotting.

Rename and Scan

RENAME

rename <source> <destination>

Renames a key, replacing the destination if needed.

RENAMENX

renamenx <source> <destination>

Renames a key only when the destination does not exist.

SCAN

scan <cursor> [match <pattern>] [count <n>]

Returns a cursor page of keys in deterministic sorted order.

Example:

scan 0 match app:* count 10

Database Introspection and Maintenance

DBSIZE and COUNT

dbsize
count

Both return the live key count.

LIST

list

Returns live key/value entries.

CLEAR and FLUSHDB

clear
flushdb

Clears the current keyspace. When auth/RBAC is enabled, this requires the clear permission.

SAVE and SNAPSHOT

save
snapshot

Write a physical encrypted snapshot, seal the active WAL segment, open a new active segment, and prune retained sealed segments according to runtime policy.

Logical Backup and Restore

BACKUP

backup
backup to <path>
backup verify <logical-dump-json>
backup verify from <path>

Logical backup commands operate on JSON dumps rather than physical storage files.

• backup returns the logical dump inline
• backup to <path> writes a server-local dump under the configured backup directory
• backup verify ... validates dump structure and, for file-backed dumps, verifies the manifest sidecar

Example:

backup to nightly.json

RESTORE

restore <logical-dump-json>
restore from <path>
restore check <logical-dump-json>
restore check from <path>

Restore commands replace the current keyspace with the live entries from a validated logical backup. restore check ... performs validation without mutating engine state or WAL.

Example:

restore check from nightly.json

Transactions

MULTI

multi

Starts queueing commands for the current connection.

EXEC

exec

Applies the queued commands as one single-node atomic WAL-backed batch if every queued command succeeds.

DISCARD

discard

Drops the queued transaction.

Current boundaries:

• transactions are single-node only
• transaction lifetimes are bounded by a server-side timeout
• sequence-tagged or pipelined requests are rejected while a transaction is active
• maintenance mode rejects transaction entry and commit

Maintenance Mode

MAINTENANCE

maintenance on
maintenance off
maintenance status

Maintenance mode is a persisted read-only admin mode. It survives restart through a sentinel file under the data directory.

While maintenance mode is enabled:

• reads, info, metrics, metrics prom, backup verification flows, show *, whoami, and maintenance status remain available
• mutating writes, restore flows, and transaction commands are rejected

HA and Replication

HEALTH

health

Returns machine-readable readiness and role state as key/value fields.

SHOW CLUSTER

show cluster

Returns cluster state such as local role, term, leader ID, quorum size, member count, sync policy, commit sequence, and local applied sequence.

SHOW REPLICATION

show replication

Returns replication diagnostics such as role, node ID, group ID, leader hint, commit sequence, retention floor, paused state, and health reason.

CLUSTER JOIN and CLUSTER REMOVE

cluster join <node-id> <host:port>
cluster remove <node-id>

Updates cluster membership from the leader. The <node-id> must be stable across restarts, and <host:port> must be reachable by peer replication traffic.

Replication Controls

promote follower
pause replication
resume replication

These are administrative controls for exceptional operational workflows. Normal failover uses leader election; application writes should target the current leader.

User, Role, and Grant Management

These commands are server-side administrative commands. The engine remains unaware of users and roles.

User and Role Lifecycle

create user <username> password <password>
alter user <username> password <password>
drop user <username>
create role <role>
drop role <role>

Example:

create user jane password SecurePass123

Password policy currently requires at least 12 characters with at least one ASCII letter and one ASCII digit.

Role Assignment

grant role <role> to <username>
revoke role <role> from <username>

Example:

grant role readonly to jane

Permission Grants

grant permission <permission> [on <pattern>] to <role>
revoke permission <permission> [on <pattern>] from <role>

The on <pattern> clause is optional. When omitted, the pattern defaults to *.

Example:

grant permission read on app:* to readonly

Grant Introspection

show users
show roles
show grants
show grants for user <username>
show grants for role <role>
whoami

Use show grants for the current authenticated user, or the for user / for role forms for administrative inspection.

Client-Local Commands

help
exit
quit

These commands are handled by the client REPL and are never sent to the server.