redis://wire-reference

Redis Protocol Cheat Sheet

Command shapes, RESP replies, and edge conditions for developers building clients, proxies, protocol test suites or Redis-compatible servers.

RESP primer

The minimum parser surface

Requests

Clients send commands as arrays of bulk strings. The first element is the command name.

*2\r\n$3\r\nGET\r\n$3\r\nkey\r\n

RESP2 replies

+ simple string, - error, : integer, $ bulk string, * array.

Null is encoded as $-1\r\n or *-1\r\n, depending on context.

RESP3 replies

Adds native _ null, # boolean, , double, % map, ~ set, and > push.

Use HELLO 3 to switch a connection from RESP2 to RESP3.

Errors

Errors are RESP error replies: -PREFIX message\r\n. The prefix is the stable part clients should classify.

Common prefixes include ERR, WRONGTYPE, NOAUTH, NOSCRIPT, MOVED, ASK, and READONLY.

wire types

RESP type bytes

How the selected protocol represents each reply data type on the wire.

RESP2 7 wire forms
+

simple

+OK\r\n

Short non-binary string; no CR or LF inside payload.

-

error

-ERR message\r\n

Error reply; classify Redis errors by the prefix before the first space.

:

int

:1000\r\n

Signed decimal integer terminated by CRLF.

$

bulk

$5\r\n hello\r\n

Length-prefixed binary string; length is bytes, not characters.

$-1

null-bulk

$-1\r\n

RESP2 null for missing bulk-string values.

*

array

*2\r\n $3\r\n one\r\n $3\r\n two\r\n

Count followed by that many nested RESP values.

*-1

null-array

*-1\r\n

RESP2 null for aggregate outcomes such as blocking pop timeout.

RESP3 15 wire forms
+

simple

+OK\r\n

Short non-binary string; still available in RESP3.

-

error

-ERR message\r\n

Simple error; same prefix convention as RESP2.

:

int

:1000\r\n

Signed decimal integer.

$

blob

$5\r\n hello\r\n

RESP3 name for length-prefixed binary strings.

_

null

_\r\n

Dedicated null type; replaces RESP2 null bulk/array ambiguity.

#

bool

#t\r\n

#t for true, #f for false.

,

double

,1.23\r\n

Floating-point value; also supports inf, -inf, and nan.

(

big-number

(3492890328409238509324850943850943825024385\r\n

Integer outside signed 64-bit range.

!

blob-error

!20\r\n SYNTAX invalid token\r\n

Length-prefixed error payload.

=

verbatim

=15\r\n txt:Some string\r\n

Length-prefixed string with a 3-byte format tag and colon.

*

array

*2\r\n +one\r\n +two\r\n

Ordered aggregate of nested RESP values.

%

map

%1\r\n +field\r\n +value\r\n

Key/value aggregate; count is number of pairs.

|

attribute

|1\r\n +ttl\r\n :30\r\n

Out-of-band metadata attached to the following reply.

~

set

~2\r\n +one\r\n +two\r\n

Unordered aggregate of unique values.

>

push

>3\r\n +message\r\n +channel\r\n +payload\r\n

Server-initiated data not necessarily tied to a request.

reply notation
simpleRESP simple string bulkRESP2 bulk string blobRESP3 blob string intRESP integer null-bulkRESP2 $-1 null-arrayRESP2 *-1 nullRESP3 _ error<PREFIX>RESP error; classify by prefix replyany nested RESP reply
79 commands visible

category

Connection / Server

#

Connection / Server

PING

connections
$ PING [message]

Params

  • message: optional bulk string echoed back instead of PONG.

Reply

Implementation notes

  • Allowed in Pub/Sub mode; with a message it is useful as an echo/latency probe.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.

Connection / Server

HELLO

connectionsauth
$ HELLO [protover [AUTH username password] [SETNAME clientname]]

Params

  • protover: optional 2 or 3.
  • AUTH: authenticate during handshake.
  • SETNAME: assign client name.

Reply

Implementation notes

  • Switches the connection protocol version. Invalid protover is an error.
  • RESP3 clients should be ready for push messages outside direct request/reply flow.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Unsupported protover -> -NOPROTO unsupported protocol version.
  • AUTH option failure -> -WRONGPASS invalid username-password pair or user disabled.

Connection / Server

AUTH

connectionsauth
$ AUTH [username] password

Params

  • username: ACL user, defaults to default user when omitted.
  • password: secret.

Reply

Implementation notes

  • After an auth error, the connection remains open but unauthenticated.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Bad credentials -> -WRONGPASS invalid username-password pair or user disabled.
  • AUTH when no password is configured -> -ERR AUTH <password> called without any password configured.

Connection / Server

SELECT

connections
$ SELECT index

Params

  • index: zero-based logical database number.

Reply

Implementation notes

  • Database selection is per connection. Redis Cluster only supports database 0.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Invalid DB index -> -ERR invalid DB index.
  • Cluster mode DB other than 0 -> -ERR SELECT is not allowed in cluster mode.

Connection / Server

CLIENT

connections
$ CLIENT subcommand [arg ...]

Params

  • subcommand: SETNAME, GETNAME, ID, INFO, LIST, KILL, PAUSE, REPLY, TRACKING, etc.

Reply

Implementation notes

  • CLIENT REPLY can suppress replies; client implementations must not assume every command yields a response after it is changed.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Unknown subcommand or blocked operation -> -ERR with subcommand-specific text.
  • CLIENT REPLY OFF/SKIP changes whether later errors are delivered to the client.

Connection / Server

QUIT

connections
$ QUIT

Params

  • No arguments.

Reply

Implementation notes

  • Modern clients can close the socket directly; still useful for protocol compatibility.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.

Connection / Server

INFO

server
$ INFO [section]

Params

  • section: optional section name such as server, clients, memory, stats, replication, commandstats, cluster.

Reply

Implementation notes

  • Treat as textual diagnostics, not a stable machine schema.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.

Connection / Server

COMMAND

server
$ COMMAND [subcommand [arg ...]]

Params

  • subcommand: optional DOCS, INFO, COUNT, GETKEYS, GETKEYSANDFLAGS, LIST.

Reply

Implementation notes

  • Use for capability discovery instead of hard-coding server command tables.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.

category

Generic Keys

#

Generic Keys

EXISTS

keys
$ EXISTS key [key ...]

Params

  • key: one or more keys; duplicates are counted independently.

Reply

Implementation notes

  • A repeated existing key increments the count each time it appears.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Generic Keys

DEL

keys
$ DEL key [key ...]

Params

  • key: one or more keys.

Reply

Implementation notes

  • Synchronous deletion; large values can block the server briefly.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.

Generic Keys

UNLINK

keys
$ UNLINK key [key ...]

Params

  • key: one or more keys.

Reply

Implementation notes

  • Removes names from keyspace immediately and frees memory asynchronously.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.

Generic Keys

TYPE

keys
$ TYPE key

Params

  • key: key to inspect.

Reply

Implementation notes

  • Returns none for missing keys; not an error.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Generic Keys

EXPIRE

keys
$ EXPIRE key seconds [NX | XX | GT | LT]

Params

  • seconds: TTL in seconds.
  • NX/XX/GT/LT: optional condition.

Reply

Implementation notes

  • Missing keys return 0. Condition failures also return 0. Non-positive expiry deletes immediately and returns 1 if the key existed.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • Missing key and NX/XX/GT/LT condition miss are not errors; both return integer 0.

Generic Keys

PEXPIRE

keys
$ PEXPIRE key milliseconds [NX | XX | GT | LT]

Params

  • milliseconds: TTL in ms.
  • NX/XX/GT/LT: optional condition.

Reply

Implementation notes

  • Same semantics as EXPIRE but millisecond precision: missing key and condition miss both return 0.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • Missing key and NX/XX/GT/LT condition miss are not errors; both return integer 0.

Generic Keys

TTL

keys
$ TTL key

Params

  • key: key to inspect.

Reply

Implementation notes

  • Do not confuse -1 with a missing key.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Generic Keys

PTTL

keys
$ PTTL key

Params

  • key: key to inspect.

Reply

Implementation notes

  • Millisecond variant of TTL.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Generic Keys

SCAN

keys
$ SCAN cursor [MATCH pattern] [COUNT count] [TYPE type]

Params

  • cursor: cursor from previous call; start with 0.
  • MATCH/COUNT/TYPE: optional filters/hints.

Reply

Implementation notes

  • Cursor 0 means iteration complete. COUNT is a hint; duplicates can appear.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.

Generic Keys

KEYS

keys
$ KEYS pattern

Params

  • pattern: glob-style pattern.

Reply

Implementation notes

  • Blocking O(N) operation; avoid on production hot paths.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.

Generic Keys

RENAME

keys
$ RENAME key newkey

Params

  • key: existing key.
  • newkey: destination name.

Reply

Implementation notes

  • Errors if source is missing. Overwrites destination if it exists.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • Missing source key -> -ERR no such key.

category

Strings

#

Strings

GET

strings
$ GET key

Params

  • key: string key.

Reply

Implementation notes

  • Wrong type returns WRONGTYPE error.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Strings

SET

strings
$ SET key value [NX | XX] [GET] [EX seconds | PX ms | EXAT unix | PXAT ms-unix | KEEPTTL]

Params

  • value: binary-safe bulk string.
  • NX/XX: conditional set.
  • GET: return previous value.
  • expiry option: optional TTL behavior.

Reply

Implementation notes

  • SET replaces older SETNX/SETEX/PSETEX patterns. GET changes the reply type. Null can mean either previous value missing or conditional write skipped.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • NX/XX condition miss is not an error; return null and do not write.
  • With GET, previous missing value returns null but the write still succeeds.
  • Conflicting expiry or condition options -> -ERR syntax error.
  • With GET, an existing non-string value -> -WRONGTYPE.

Strings

MGET

strings
$ MGET key [key ...]

Params

  • key: one or more keys.

Reply

Implementation notes

  • Array length always matches requested key count.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Strings

MSET

strings
$ MSET key value [key value ...]

Params

  • key value: one or more pairs.

Reply

Implementation notes

  • Atomic across all specified keys.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.

Strings

INCR

strings
$ INCR key

Params

  • key: integer-encoded string or missing key.

Reply

Implementation notes

  • Missing key is initialized to 0 before increment. Errors on non-integer or overflow.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • Value is not a base-10 signed 64-bit integer -> -ERR value is not an integer or out of range.
  • Overflow -> -ERR increment or decrement would overflow.

Strings

DECR

strings
$ DECR key

Params

  • key: integer-encoded string or missing key.

Reply

Implementation notes

  • Missing key is initialized to 0 before decrement. Errors on non-integer or overflow.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • Value is not a base-10 signed 64-bit integer -> -ERR value is not an integer or out of range.
  • Overflow -> -ERR increment or decrement would overflow.

Strings

APPEND

strings
$ APPEND key value

Params

  • value: bytes appended to current string.

Reply

Implementation notes

  • Missing key is treated as empty string. Wrong type errors.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.

Strings

STRLEN

strings
$ STRLEN key

Params

  • key: string key.

Reply

Implementation notes

  • Length is bytes, not characters.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Strings

GETRANGE

strings
$ GETRANGE key start end

Params

  • start/end: inclusive byte offsets; negative indexes count from end.

Reply

Implementation notes

  • Offsets are byte-based and inclusive.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Invalid range indexes -> -ERR value is not an integer or out of range.

category

Hashes

#

Hashes

HGET

hashes
$ HGET key field

Params

  • field: hash field name.

Reply

Implementation notes

  • Wrong type errors if key exists and is not a hash.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Hashes

HSET

hashes
$ HSET key field value [field value ...]

Params

  • field value: one or more field/value pairs.

Reply

Implementation notes

  • Existing fields are overwritten but not counted as new.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.

Hashes

HMGET

hashes
$ HMGET key field [field ...]

Params

  • field: one or more fields.

Reply

Implementation notes

  • Array length matches requested fields, even when key is missing.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Hashes

HGETALL

hashes
$ HGETALL key

Params

  • key: hash key.

Reply

Implementation notes

  • Missing key returns empty array/map. Field order is not stable.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Hashes

HDEL

hashes
$ HDEL key field [field ...]

Params

  • field: one or more fields.

Reply

Implementation notes

  • Missing fields and missing keys are ignored.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.

Hashes

HEXISTS

hashes
$ HEXISTS key field

Params

  • field: field to test.

Reply

Implementation notes

  • RESP2 and RESP3 still use integer truth here.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Hashes

HSCAN

hashes
$ HSCAN key cursor [MATCH pattern] [COUNT count] [NOVALUES]

Params

  • cursor: hash iterator cursor.
  • NOVALUES: return fields only when supported.

Reply

Implementation notes

  • Cursor semantics match SCAN; COUNT is a hint and duplicates can appear.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

category

Lists

#

Lists

LPUSH

lists
$ LPUSH key element [element ...]

Params

  • element: one or more values inserted at head.

Reply

Implementation notes

  • Multiple elements are inserted left-to-right at the head; final order is reversed relative to argument order.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.

Lists

RPUSH

lists
$ RPUSH key element [element ...]

Params

  • element: one or more values inserted at tail.

Reply

Implementation notes

  • Creates list when key is missing; wrong type errors.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.

Lists

LPOP

lists
$ LPOP key [count]

Params

  • count: optional number of elements.

Reply

Implementation notes

  • Reply shape changes when count is present.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.

Lists

RPOP

lists
$ RPOP key [count]

Params

  • count: optional number of elements.

Reply

Implementation notes

  • Reply shape changes when count is present.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.

Lists

LRANGE

lists
$ LRANGE key start stop

Params

  • start/stop: inclusive indexes; negative indexes count from tail.

Reply

Implementation notes

  • stop is inclusive, unlike many programming-language slices.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Lists

LLEN

lists
$ LLEN key

Params

  • key: list key.

Reply

Implementation notes

  • Wrong type errors.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Lists

BLPOP

lists
$ BLPOP key [key ...] timeout

Params

  • key: one or more lists in priority order.
  • timeout: seconds; 0 blocks indefinitely.

Reply

Implementation notes

  • Connection blocks until data, timeout, or disconnect. First non-empty key wins by argument order.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • Timeout is not an error; return null array/null when no element becomes available.
  • Negative timeout -> -ERR timeout is negative.

Lists

BRPOP

lists
$ BRPOP key [key ...] timeout

Params

  • key: one or more lists in priority order.
  • timeout: seconds; 0 blocks indefinitely.

Reply

Implementation notes

  • Blocking tail pop. Same timeout/null semantics as BLPOP.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • Timeout is not an error; return null array/null when no element becomes available.
  • Negative timeout -> -ERR timeout is negative.

category

Sets

#

Sets

SADD

sets
$ SADD key member [member ...]

Params

  • member: one or more set members.

Reply

Implementation notes

  • Existing members are ignored and not counted.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.

Sets

SREM

sets
$ SREM key member [member ...]

Params

  • member: one or more set members.

Reply

Implementation notes

  • Missing members and missing keys are ignored.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.

Sets

SMEMBERS

sets
$ SMEMBERS key

Params

  • key: set key.

Reply

Implementation notes

  • Ordering is unspecified. Missing key returns empty collection.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Sets

SISMEMBER

sets
$ SISMEMBER key member

Params

  • member: value to test.

Reply

Implementation notes

  • Missing key returns 0.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Sets

SCARD

sets
$ SCARD key

Params

  • key: set key.

Reply

Implementation notes

  • Wrong type errors.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Sets

SSCAN

sets
$ SSCAN key cursor [MATCH pattern] [COUNT count]

Params

  • cursor: set iterator cursor.

Reply

Implementation notes

  • Cursor semantics match SCAN; duplicates can appear.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

category

Sorted Sets

#

Sorted Sets

ZADD

sorted sets
$ ZADD key [NX | XX] [GT | LT] [CH] [INCR] score member [score member ...]

Params

  • score member: one or more pairs.
  • CH: count changed members.
  • INCR: increment score of a single member.

Reply

Implementation notes

  • Scores parse as doubles. NaN is rejected. INCR accepts only one pair. With INCR, a failed condition returns null instead of an integer count.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • Invalid score -> -ERR value is not a valid float.
  • With INCR, a failed NX/XX/GT/LT condition is not an error; return null and leave score unchanged.
  • Conflicting NX/XX/GT/LT options -> -ERR syntax error.

Sorted Sets

ZRANGE

sorted sets
$ ZRANGE key start stop [BYSCORE | BYLEX] [REV] [LIMIT offset count] [WITHSCORES]

Params

  • start/stop: index, score, or lex bounds depending on mode.
  • WITHSCORES: include score after each member.

Reply

Implementation notes

  • WITHSCORES returns scores as strings; clients may parse them as doubles if they need numeric comparison.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Sorted Sets

ZREM

sorted sets
$ ZREM key member [member ...]

Params

  • member: one or more members.

Reply

Implementation notes

  • Missing members and missing keys are ignored.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.

Sorted Sets

ZSCORE

sorted sets
$ ZSCORE key member

Params

  • member: sorted-set member.

Reply

Implementation notes

  • Clients should preserve exact text if they do not want floating-point round-trip changes.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Missing member/key is not an error; return null.

Sorted Sets

ZRANK

sorted sets
$ ZRANK key member [WITHSCORE]

Params

  • WITHSCORE: optionally include score.

Reply

Implementation notes

  • Rank is zero-based and ascending by score.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Sorted Sets

ZCARD

sorted sets
$ ZCARD key

Params

  • key: sorted set key.

Reply

Implementation notes

  • Wrong type errors.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Sorted Sets

ZSCAN

sorted sets
$ ZSCAN key cursor [MATCH pattern] [COUNT count]

Params

  • cursor: sorted-set iterator cursor.

Reply

Implementation notes

  • Cursor semantics match SCAN; scores are returned as bulk/blob strings.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

category

Streams

#

Streams

XADD

streams
$ XADD key [NOMKSTREAM] [KEEPREF | DELREF | ACKED] [MAXLEN | MINID [= | ~] threshold [LIMIT count]] id field value [field value ...]

Params

  • id: * for server-generated ID, or explicit ms-seq ID.
  • field value: one or more pairs.

Reply

Implementation notes

  • IDs must be greater than the stream top ID except special forms. Field/value arity must be even. NOMKSTREAM turns missing-stream creation into a null reply, not an error.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • NOMKSTREAM with a missing stream is not an error; return null and create nothing.
  • ID not greater than stream top item -> -ERR The ID specified in XADD is equal or smaller than the target stream top item.
  • MAXLEN/MINID syntax or bad ID -> -ERR with stream-specific text.

Streams

XRANGE

streams
$ XRANGE key start end [COUNT count]

Params

  • start/end: IDs or -/+ bounds.
  • COUNT: optional max entries.

Reply

Implementation notes

  • Inclusive range. Missing stream returns empty array.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.

Streams

XREAD

streams
$ XREAD [COUNT count] [BLOCK milliseconds] STREAMS key [key ...] id [id ...]

Params

  • STREAMS: keys followed by matching last-seen IDs.
  • BLOCK: optional blocking wait.

Reply

Implementation notes

  • With BLOCK, Redis returns synchronously if data is already available. If it waits, the reply is not an echo of every requested STREAMS key; for a single XADD that wakes the read, it contains the stream that received the entry. BLOCK 0 waits indefinitely.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • No data without BLOCK and timeout with BLOCK are not errors; both return null array/null.
  • Malformed stream ID or COUNT/BLOCK value -> -ERR with stream-specific text.

Streams

XGROUP

streams
$ XGROUP subcommand key group [arg ...]

Params

  • subcommand: CREATE, SETID, DESTROY, CREATECONSUMER, DELCONSUMER, etc.

Reply

Implementation notes

  • CREATE with MKSTREAM can create an empty stream. Duplicate group is BUSYGROUP error.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • Missing stream/group/consumer state can produce -NOGROUP or -BUSYGROUP depending on subcommand.
  • Bad stream ID -> -ERR with stream-specific text.

Streams

XREADGROUP

streams
$ XREADGROUP GROUP group consumer [COUNT count] [BLOCK ms] [NOACK] STREAMS key [key ...] id [id ...]

Params

  • group/consumer: consumer group identity.
  • id: > for new messages or explicit pending IDs.

Reply

Implementation notes

  • Using > reads never-delivered entries. With BLOCK, Redis returns synchronously if data is already available. If it waits, the reply is not an echo of every requested STREAMS key; for a single XADD that wakes the read, it contains the stream that received the entry.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • Unknown group or missing key group state -> -NOGROUP.
  • No data without BLOCK and timeout with BLOCK are not errors; both return null array/null.

Streams

XACK

streams
$ XACK key group id [id ...]

Params

  • id: one or more stream entry IDs.

Reply

Implementation notes

  • Only pending entries in the group are counted.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Existing key with incompatible type -> -WRONGTYPE Operation against a key holding the wrong kind of value.
  • Cluster slot owner mismatch -> -MOVED; temporary migration target -> -ASK, then retry after ASKING.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • Unknown group or missing key group state -> -NOGROUP.

category

Pub/Sub

#

Pub/Sub

SUBSCRIBE

pub/sub
$ SUBSCRIBE channel [channel ...]

Params

  • channel: one or more channels.

Reply

Implementation notes

  • RESP2 subscribed mode restricts allowed commands. RESP3 models Pub/Sub as push data.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • In RESP2 subscribed mode, only a limited command set is accepted; other commands return -ERR.
  • Malformed channel arguments -> -ERR wrong number of arguments.

Pub/Sub

PSUBSCRIBE

pub/sub
$ PSUBSCRIBE pattern [pattern ...]

Params

  • pattern: glob-style channel pattern.

Reply

Implementation notes

  • Pattern matching happens server-side against published channel names.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • In RESP2 subscribed mode, only a limited command set is accepted; other commands return -ERR.
  • Malformed pattern arguments -> -ERR wrong number of arguments.

Pub/Sub

PUBLISH

pub/sub
$ PUBLISH channel message

Params

  • channel: destination channel.
  • message: payload bytes.

Reply

Implementation notes

  • Delivery is fire-and-forget; messages are not persisted.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • Invalid argument count -> -ERR wrong number of arguments.

Pub/Sub

UNSUBSCRIBE

pub/sub
$ UNSUBSCRIBE [channel [channel ...]]

Params

  • channel: optional channels; omitted means all.

Reply

Implementation notes

  • When subscription count reaches zero, RESP2 connection returns to normal command mode.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.

category

Transactions

#

Transactions

MULTI

transactions
$ MULTI

Params

  • No arguments.

Reply

Implementation notes

  • Subsequent commands are queued until EXEC/DISCARD, except immediate syntax/queueing errors.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Nested MULTI -> -ERR MULTI calls can not be nested.

Transactions

EXEC

transactions
$ EXEC

Params

  • No arguments.

Reply

Implementation notes

  • Runtime command errors appear as error elements inside the EXEC reply array.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Watched key changed -> null array/null, not an error.
  • Queued command failure before EXEC -> -EXECABORT Transaction discarded because of previous errors.

Transactions

DISCARD

transactions
$ DISCARD

Params

  • No arguments.

Reply

Implementation notes

  • Clears queued transaction and unwatches keys for the connection.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Without MULTI -> -ERR DISCARD without MULTI.

Transactions

WATCH

transactions
$ WATCH key [key ...]

Params

  • key: one or more keys to monitor.

Reply

Implementation notes

  • If any watched key changes before EXEC, EXEC returns null.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Inside MULTI -> -ERR WATCH inside MULTI is not allowed.

Transactions

UNWATCH

transactions
$ UNWATCH

Params

  • No arguments.

Reply

Implementation notes

  • Clears all watched keys for the connection.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.

category

Scripting

#

Scripting

EVAL

scripting
$ EVAL script numkeys [key [key ...]] [arg [arg ...]]

Params

  • script: Lua source.
  • numkeys: number of following key arguments.
  • arg: remaining script arguments.

Reply

Implementation notes

  • Scripts are atomic. Keys must be declared via numkeys for cluster/key tracking correctness.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • Script runtime error -> -ERR Error running script.
  • Wrong numkeys or undeclared cluster keys -> -ERR/-CROSSSLOT depending on mode.

Scripting

EVALSHA

scripting
$ EVALSHA sha1 numkeys [key [key ...]] [arg [arg ...]]

Params

  • sha1: cached script digest.
  • numkeys/key/arg: same as EVAL.

Reply

Implementation notes

  • After NOSCRIPT, clients can retry with EVAL or reload the script with SCRIPT LOAD.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Non-integer integer argument or out-of-range value -> -ERR value is not an integer or out of range.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • Unknown SHA1 -> -NOSCRIPT No matching script. Please use EVAL.
  • Script runtime error -> -ERR Error running script.

Scripting

SCRIPT LOAD

scripting
$ SCRIPT LOAD script

Params

  • script: Lua source to cache.

Reply

Implementation notes

  • Loads but does not execute the script.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Write attempted against a read-only replica or read-only script context -> -READONLY.
  • Invalid Lua source -> -ERR Error compiling script.

Scripting

SCRIPT EXISTS

scripting
$ SCRIPT EXISTS sha1 [sha1 ...]

Params

  • sha1: one or more script digests.

Reply

Implementation notes

  • Array order matches requested digests.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.

category

Cluster Basics

#

Cluster Basics

CLUSTER SLOTS

cluster
$ CLUSTER SLOTS

Params

  • No arguments.

Reply

Implementation notes

  • Prefer CLUSTER SHARDS for newer clients when available, but SLOTS is widely implemented.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Cluster support disabled -> -ERR This instance has cluster support disabled.

Cluster Basics

CLUSTER NODES

cluster
$ CLUSTER NODES

Params

  • No arguments.

Reply

Implementation notes

  • Textual format; robust parsers must handle flags and optional endpoint metadata.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Cluster support disabled -> -ERR This instance has cluster support disabled.

Cluster Basics

ASKING

cluster
$ ASKING

Params

  • No arguments.

Reply

Implementation notes

  • Send before the redirected command after an ASK redirect, on the target connection.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Cluster support disabled -> -ERR This instance has cluster support disabled.

Cluster Basics

READONLY

clusterreplication
$ READONLY

Params

  • No arguments.

Reply

Implementation notes

  • Allows readonly commands against cluster replicas when the key slot is served by the replica's master.

Error cases

  • Bad arity or malformed options -> -ERR wrong number of arguments or -ERR syntax error.
  • Cluster support disabled -> -ERR This instance has cluster support disabled.