redis-cli

The interactive Redis client, monitor, cluster manager, latency tester, big-keys scanner, and live key-space visualiser. One C file (src/redis-cli.c, 11,144 lines) implements the lot.

Active contributors: antirez, Oran Agra, Itamar Haber, Yossi Gottlieb, Binbin.

Purpose

redis-cli is the canonical client for Redis. It speaks RESP over TCP, Unix sockets, or TLS, and ships modes for:

• Interactive REPL (redis-cli).
• One-shot command execution (redis-cli SET foo bar).
• Pipe mode (redis-cli --pipe < cmds.txt to bulk-load with pipelining).
• MONITOR mode (redis-cli MONITOR) printing every command the server sees.
• Latency probing (--latency, --latency-history, --latency-dist, --intrinsic-latency).
• Big key / hot key scanning (--bigkeys, --memkeys, --hotkeys).
• Live keyspace stats (--stat).
• Slot scanning and cluster management (--cluster <subcommand>).
• LRU testing (--lru-test).
• RDB dumping over the wire (--rdb).
• Functional --scan over the entire keyspace.

Source layout

File	Role
src/redis-cli.c	The whole CLI: argument parsing, REPL, all subcommands. main() dispatches into cli* functions.
src/cli_common.c, src/cli_common.h	Shared helpers (TLS bootstrap, password prompting, RESP printing, history file). Also linked into redis-benchmark.
src/cli_commands.c, src/cli_commands.h	Command auto-completion table — generated from the JSON specs so the REPL can hint argument names.
deps/linenoise/	The line-editing library used by the REPL. Tab completion, history, multi-line edit.
deps/hiredis/	The synchronous Redis client library. Provides connection + RESP encoding/decoding.

Architecture

graph TD
    main[main() src/redis-cli.c] --> args[parseOptions]
    args -->|--cluster X| cluster[clusterManager*]
    args -->|--bigkeys etc| stat[scanMode / statMode]
    args -->|--latency etc| lat[latencyMode]
    args -->|--rdb| rdb[getRDB]
    args -->|none of the above| repl[REPL via linenoise]
    repl --> hiredis[redisCommand via deps/hiredis]
    cluster --> hiredis
    stat --> hiredis

Almost every code path eventually goes through hiredis's redisCommand to send a RESP packet and redisReply to decode the reply.

Key subcommands

Cluster manager (--cluster ...)

The cluster mode implements roughly the original redis-trib.rb Ruby tool, rewritten in C around 2018. Subcommands:

• --cluster create <addr...> — bootstrap a fresh cluster.
• --cluster check <addr> — sanity-check a live cluster.
• --cluster reshard — interactive slot redistribution.
• --cluster rebalance — automatic slot redistribution by weight.
• --cluster add-node, --cluster del-node.
• --cluster fix — repair common slot-state bugs.
• --cluster import — copy keys from a non-cluster source.
• --cluster call, --cluster info.

The implementation is a few thousand lines starting from clusterManagerCommand in src/redis-cli.c. Each subcommand parses options into a clusterManagerCommand struct and dispatches to a handler.

--bigkeys, --memkeys, --hotkeys

These mode iterate the whole keyspace with SCAN and tally per-type or per-key statistics:

• --bigkeys finds the top-N largest objects by element count for each type.
• --memkeys ranks by MEMORY USAGE.
• --hotkeys requires maxmemory-policy allkeys-lfu/volatile-lfu and ranks by OBJECT FREQ.

--latency family

• --latency shows live latency stats (min/max/avg).
• --latency-history does the same in time windows.
• --latency-dist builds a colour-coded histogram (uses ANSI escapes).
• --intrinsic-latency <seconds> measures the OS scheduler / clock jitter without involving Redis at all (useful to find a baseline before blaming the server).

--pipe

Reads RESP-encoded commands from stdin and pipelines them to the server, reading replies asynchronously. The implementation is a state machine that pushes bytes out as fast as the server reads them and reads replies in parallel. Useful for bulk imports — order-of-magnitude faster than executing commands one at a time.

The companion script in src/cli_commands.c is redis-cli style; for generating RESP-encoded input, see redis-benchmark's --csv/inline modes or the standalone helper in older docs.

--rdb <file>

Asks the server for an RDB dump and writes it locally. Implemented by sending a SYNC/REPLCONF handshake and reading the binary RDB payload that the server normally streams to a replica. The server has to be willing — under stricter ACLs the requesting user needs the replication permission.

--scan

Walks the keyspace using SCAN (cluster-aware). Output one key per line. Filters via --pattern <glob> and --type <list|set|...>.

Configuration

redis-cli honours environment variables and dotfile-style options:

Variable / flag	Purpose
REDISCLI_AUTH	Default password (avoids -a on the command line, which leaks via ps).
REDISCLI_HISTFILE	Override the ~/.rediscli_history location.
--user, --pass	ACL auth.
--tls, --cacert, --cert, --key	TLS.
--no-raw / --no-color	Output formatting.
--csv	CSV output.
--json	JSON output (RESP3 only).
--quoted-input	Re-quote command arguments using a special syntax.

Testing redis-cli

Tests live in tests/integration/redis-cli.tcl. They cover the REPL semantics, pipe mode, the cluster manager, and the latency family. The big-keys scanner has its own tests in tests/integration/redis-cli.tcl too. To run only those:

./runtest --single integration/redis-cli

Where to start modifying

• A new command shows up but redis-cli doesn't tab-complete it — regenerate the auto-completion table by running make commands.def (which also rebuilds src/cli_commands.c).
• A new --xxxx mode — add an option in parseOptions, add a state flag on the global config, route into a xxxxMode() function near the bottom of src/redis-cli.c.
• Cluster manager bug — search for clusterManager in src/redis-cli.c. There is no separate file; everything is in one place.