valkey-cli Features Operators Miss: Env Vars, valkeys:// URIs, --json and Cluster Helpers

Most teams use valkey-cli the way they used redis-cli: -h, -p, -a and a command. That habit puts the password in the process list, sends KEYS * to a busy primary, and lets a shell script carry on after an (error) NOAUTH Authentication required. reply, because valkey-cli exits 0 on an error reply unless you pass -e. Valkey 9.0 added VALKEYCLI_* environment variables, 9.1 added a hidden atomic slot migration flag to --cluster, and the 9.2 release candidates add more. This post walks through the options an operator should know in valkey-cli 9.1.3: environment variables, valkeys:// URIs, --json, remote RDB transfers, key and latency scans, the cluster manager, and the modes that are risky on a production primary.

Scope and review date: November 2026. This post covers valkey-cli 9.1.3 (released 26 October 2026), with notes on 8.1.11, 9.0.7 and the 9.2.0-rc2 release candidate. Options and behaviour were checked against the valkey-cli documentation, the release notes, and the valkey-cli.c source at each tag on 10 November 2026. The commands were not run in a lab, so try them on staging first.

Which valkey-cli features depend on the version you run?

The client version decides which options exist, not the server version. A 9.1.3 valkey-cli can talk to an 8.1 server, but an 8.1 valkey-cli on a bastion host does not read VALKEYCLI_AUTH. Check the binary on every host your scripts run from.

valkey-cli --version
valkey-cli --help | grep -E 'VALKEYCLI|json|functions-rdb'

Interpretation: --version prints the client build. If the help text names REDISCLI_AUTH instead of VALKEYCLI_AUTH, you have an 8.x client.

The 9.0.0-rc1 release notes and the 9.2.0-rc1 release notes list these changes. As of November 2026 the documentation page shows VALKEYCLI_HOST and VALKEYCLI_PORT in the option defaults with no version label, but the 9.1.3 source does not read them. Treat the documentation as describing 9.2.

How do you keep the Valkey password off the command line?

With -a, the password is visible in ps output, in shell history, and in CI logs, and valkey-cli prints Warning: Using a password with '-a' or '-u' option on the command line interface may not be safe. From 9.0, valkey-cli reads VALKEYCLI_AUTH and falls back to REDISCLI_AUTH. In 9.1.3 the environment is read after the options, and it only fills the password if -a, --pass or -u did not set one, so a command-line password still wins.

# Mixed 8.x and 9.x clients: REDISCLI_AUTH works on both
export REDISCLI_AUTH="$(cat /run/secrets/valkey-monitor)"
export VALKEYCLI_HISTFILE=/dev/null   # no history file on a shared bastion
valkey-cli --user monitor -h 10.0.1.11 PING

Interpretation: PONG means the ACL user authenticated. On 9.1, the user name still comes from --user; VALKEYCLI_USER exists only in the 9.2 release candidates. On 8.1.11, only the REDISCLI_* names exist, which is why the fallback name is the safe choice for a mixed fleet.

--askpass prompts for the password and ignores both -a and the environment variable.

History needs its own attention. Since 8.0, valkey-cli keeps all commands in memory for the session, but it does not write sensitive commands to ~/.valkeycli_history. In the 9.1.3 source these include AUTH, ACL SETUSER and CONFIG SET requirepass. A SET of a customer record still lands in the file, so setting the history file to /dev/null is the simple fix on shared hosts.

How do valkeys:// URIs work?

-u accepts valkey://, valkeys://, redis:// and rediss://, in the form scheme://[user:password@]host[:port][/db]. The valkeys and rediss schemes turn on TLS. Query parameters are not supported, so CA and client certificate paths still go in flags.

export VALKEYCLI_AUTH="$(cat /run/secrets/valkey-ops)"
valkey-cli -u valkeys://valkey-prod.internal:6380/0 \
  --cacert /etc/valkey/tls/ca.crt --user ops PING

Interpretation: the URI carries no secret, so the password stays in the environment. Two traps come from the parser in cli_common.c:

• A user name with no colon is read as the password. valkeys://ops@host sends AUTH ops. Use --user ops instead.
• Special characters must be percent-encoded. The parser decodes %40 for @ and %3A for : in the user and password parts.

A valkey-cli built without TLS rejects the scheme with valkeys:// is only supported when valkey-cli is compiled with OpenSSL.

How do you get scriptable output from valkey-cli with --json?

--json asks for RESP3 with HELLO 3 and converts the reply: maps become JSON objects, arrays and sets become arrays, nil becomes null, and RESP3 booleans become true or false. If HELLO 3 fails, the client prints the error and carries on in RESP2. Pass -2 to force RESP2, which turns maps such as the CONFIG GET reply into flat arrays. --quoted-json escapes non-ASCII and binary bytes, which matters when values are not UTF-8.

valkey-cli -e --json CONFIG GET maxmemory maxmemory-policy \
  | jq -r '.maxmemory'

Interpretation: in RESP3, CONFIG GET returns a map, so jq can read each parameter by name. A value of "0" for maxmemory means no memory limit is set.

Two behaviours from the 9.1.3 source break naive scripts:

• Some commands always print raw text. INFO, CLUSTER NODES, CLUSTER INFO, CLIENT LIST, CLIENT INFO, MEMORY DOCTOR, LATENCY DOCTOR and a few DEBUG subcommands bypass the output format, even with --json. Parse INFO with grep and strip the \r.
• Errors are not JSON. Without -e, an error reply prints as error:"WRONGTYPE ..." on stdout, and the exit code is 0. With -e, the error text goes to stderr and the exit code is 1.

# INFO is raw text even with --json: strip the CR before comparing
valkey-cli -e INFO memory | tr -d '\r' \
  | awk -F: '$1 == "mem_fragmentation_ratio" { print $2 }'

Interpretation: this prints one number. Read it with used_memory in mind: a high ratio on a nearly empty instance means little, while a rising ratio on a large dataset can justify active defragmentation.

How do you script a Valkey health check with valkey-cli?

Combine authentication from the environment, -e on every call, --json for structured replies, and text parsing for INFO. Run the script with set -euo pipefail so a failure inside a pipe stops it.

Valkey keeps the master and slave strings in ROLE and INFO for compatibility, so match those words, not "primary".

How do you take a remote backup with valkey-cli --rdb?

--rdb <file> connects as a replica, sends REPLCONF capa eof and REPLCONF rdb-only 1, then SYNC, and writes the snapshot it receives to the file (- means stdout). --functions-rdb <file> also sends REPLCONF rdb-filter-only functions, so the file holds only the function libraries. The two options cannot be combined.

ts=$(date +%Y%m%dT%H%M)
valkey-cli --user backup -h 10.0.2.12 --rdb "/backup/vk-$ts.rdb.tmp" \
  && valkey-check-rdb "/backup/vk-$ts.rdb.tmp" \
  && mv "/backup/vk-$ts.rdb.tmp" "/backup/vk-$ts.rdb"

Interpretation: the file is renamed only if the transfer and the check both exit 0. valkey-check-rdb prints \o/ RDB looks OK! \o/ and exits 0 on a good file. Write to a new file each time: in 9.1.3 the client opens the target without truncating it.

Three things to know before you put this in cron:

• It forks the server. The source node runs a background save for this "replica", either to disk or straight to the socket. A filtered request such as --functions-rdb always uses the socket path. That is the same fork and copy-on-write memory cost as a full resync, so run it against a replica, here 10.0.2.12.
• The ACL user needs SYNC and REPLCONF. Both are in the @admin and @dangerous categories in 9.1.3, so give a dedicated backup user only those two commands.
• Check the exit code, and on 9.1 check the file too. The documentation says a non-zero exit means the transfer failed. In 9.1.3, if trimming the EOF marker from a diskless transfer fails, the client prints ftruncate failed and still reports success and exits 0. PR #3945 makes that exit 1 in 9.2.0-rc1. Until you run 9.2, valkey-check-rdb is what catches it.

For full backup and restore drills, including multi-part AOF and cluster rebuilds, see Valkey backups and restore drills.

How do you find big, heavy, and hot keys without KEYS?

The KEYS command page says to use KEYS in production "with extreme care" because it can stall the server on a large database. valkey-cli has four SCAN-based modes instead. All of them scan only the node you connect to, so in a cluster run them against each shard, ideally on a replica.

valkey-cli -h 10.0.2.12 --scan --pattern 'session:*' --count 1000 | wc -l
valkey-cli -h 10.0.2.12 --bigkeys -i 0.01
valkey-cli -h 10.0.2.12 --memkeys --memkeys-samples 100 -i 0.01
valkey-cli -h 10.0.2.12 --hotkeys-count 32

Interpretation:

• --scan may print a key more than once if the data changes during the scan, but it does not miss a key that existed for the whole scan. Deduplicate before you count exactly.
• --bigkeys reports the largest key of each type by element count (STRLEN, LLEN, HLEN and so on). --memkeys uses MEMORY USAGE instead, so a hash with few fields but large values shows up there and not in --bigkeys.
• --hotkeys reads OBJECT FREQ and works only when maxmemory-policy is an LFU policy. On any other policy it exits with the server's error.
• -i 0.01 sleeps 10 ms per 100 SCAN calls in these modes, which lowers the load on a busy node.

There is no --keystats option in valkey-cli 9.1.3 or 9.2.0-rc2; the parser rejects it with Unrecognized option. Server-side hot key tracking (the HOTKEYS command) is new in 9.2 and exists only in the release candidates as of November 2026.

How do you read --latency, --latency-history and --intrinsic-latency?

--latency sends PING about every 10 ms and reports the minimum, maximum and average round trip in milliseconds, measured with a millisecond clock. A reading of min: 0 is normal: it means under 1 ms, not zero. In a terminal it runs until you stop it. With output redirected, --raw, --csv or --json, it samples once (1 second by default, or the -i value) and exits, which is what the health check above uses.

valkey-cli -h 10.0.1.11 --latency-history -i 30
valkey-cli -h 10.0.1.11 --latency --json -i 10

Interpretation: --latency-history resets the statistics every 15 seconds by default (here every 30) and prints one line per window, such as min: 0, max: 3, avg: 0.21 (2850 samples) -- 30.01 seconds range. A window whose max jumps while avg stays flat points to a short stall, such as a fork, an expiry burst or a slow command. The JSON form prints {"min": ..., "max": ..., "avg": ..., "count": ...}.

--intrinsic-latency <seconds> is different: it does not connect to Valkey at all. It runs a tight loop on the local machine and reports the worst scheduling delay in microseconds. Run it on the Valkey host itself, as the documentation says, while the host is under its normal load.

valkey-cli --intrinsic-latency 60

Interpretation: the last two lines give the total runs, the average per run, and how many times longer the worst run took. If the worst run is several milliseconds, Valkey cannot respond faster than that on this host, whatever you tune in the server. For a VM baseline built on this, see running Valkey on VMs. For an incident workflow, see the Valkey latency spike runbook.

What do the valkey-cli --cluster helpers really do?

The cluster manager connects to one node, reads its view of the cluster, and then connects to every node it lists. Each subcommand has behaviour the help text does not mention. Old master option names still work beside the primary forms.

check and fix

valkey-cli --cluster check 10.0.1.11:6379 --cluster-search-multiple-owners
echo "exit=$?"

Interpretation: a healthy cluster prints [OK] All nodes agree about slots configuration. and [OK] All 16384 slots covered. and exits 0. Any open, uncovered or disputed slot makes it exit 1, so it is safe to use in monitoring.

--cluster fix changes slot ownership. Its slot-coverage prompts are hard-coded to ignore --cluster-yes and VALKEYCLI_CLUSTER_YES=1, so someone must type yes at each one. Since 9.0.5 (and 8.0.10, 7.2.14, and every 9.1 release), it assigns each uncovered, empty slot to a random primary instead of giving them all to one node. With --cluster-fix-with-unreachable-primaries, it assumes the unreachable primaries' slots are lost. Read what it proposes before you agree.

call

valkey-cli --user ops --cluster call 10.0.1.11:6379 \
  CONFIG GET maxmemory --cluster-only-primaries 2>call.err
echo "exit=$?"; cat call.err

Interpretation: stdout has one line per node, in the form 10.0.1.11:6379: maxmemory followed by the value on the next line. The reply always uses the raw format, so --json has no effect here.

backup, import, and atomic slot migration

--cluster backup host:port /dir pulls an RDB from each primary in turn, using the same transfer as --rdb, into files named valkey-node-<ip>-<port>-<node-id>.rdb, and writes the topology to nodes.json. The primaries are snapshotted one after another, so the set is not a single point in time, and each primary forks. If the cluster check finds problems, it still writes the backup and warns.

--cluster import copies a standalone instance into a cluster with SCAN and MIGRATE, and it has three traps in the 9.1.3 source:

• It reads only DB 0 of the source and logs *** Importing N keys from DB 0. Keys in other databases are left behind.
• Without --cluster-copy, MIGRATE deletes each key from the source after copying it. Add --cluster-replace only if overwriting target keys is acceptable.
• The source must not be a cluster node, and the first failed MIGRATE stops the import partway.

valkey-cli --user ops --cluster import 10.0.1.11:6379 \
  --cluster-from 10.0.9.5:6379 --cluster-from-user migrator \
  --cluster-from-askpass --cluster-copy

Interpretation: with --cluster-copy, the source keeps its data, so you can compare key counts and retry. The cluster password comes from VALKEYCLI_AUTH, and the source password is asked for interactively.

From 9.1.0, --cluster reshard and --cluster rebalance accept --cluster-use-atomic-slot-migration (PR #2755 in the 9.1.0-rc1 notes), which moves slot ranges with CLUSTER MIGRATESLOTS instead of key-by-key MIGRATE. The flag is missing from --cluster help in both 9.1.3 and 9.2.0-rc2, and --cluster fix never uses it. The atomic slot migration runbook covers when to use it.

When are --replica, --pipe, --stat and MONITOR safe in production?

--replica prints the replication stream as CSV, which is useful when you suspect a write is not replicating. It requests an RDB with data and functions filtered out, so the server still forks to produce it, and the client then appears as a replica in INFO replication. Run it on a replica of the node you are debugging, and stop it when you are done.

--pipe streams raw RESP from stdin for bulk loads, as described in the mass insertion guide. It ends with an ECHO marker, prints errors: N, replies: M, and exits 1 if any reply was an error.

./gen-resp.py | valkey-cli -h 10.0.1.11 --pipe --pipe-timeout 60 2>load.err
echo "exit=$?"; head load.err

Interpretation: each error reply is written to stderr. In a cluster, keys for slots owned by other nodes come back as MOVED errors, so pipe each node only the keys it owns. Since 9.1.0 (and 9.0.5, 8.1.8, 8.0.10, 7.2.14), the server strictly checks CRLF terminators, so a generator that writes a bare \n now gets a protocol error.

--stat prints one INFO-based line per second. Its connections column is total_connections_received, a running total, so a fast-growing number means connection churn.

Frequently asked questions

Key takeaways

Run Valkey operations with JusDB

JusDB's Valkey remote DBA team can review your operational scripts and runbooks, set up replica-offloaded backups and restore drills, and plan cluster changes such as resharding or node replacement.

Bring your Valkey versions, topology, and the scripts your team runs today. Your team approves every production change.

Related reading

• Valkey 9.1 for operators: what changed and how to upgrade
• Valkey performance tuning: memory, persistence, and cluster config
• Redis 8 vs Valkey 8 in production
• Valkey documentation: valkey-cli, the Valkey command line interface