CLIENT-LIST(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

✨ NAME ✨

okay so welcome to CLIENT-LIST(3valkey) bestie 💖 this is the page for client-list, and what does it do? it lists open connections. that's the whole job. iconic, honestly. 👑

🌸 SYNOPSIS 🌸

CLIENT LIST [TYPE <NORMAL | MASTER | REPLICA | PUBSUB>] [ID client-id
[client-id...]]  [USER username] [ADDR ip:port] [LADDR ip:port] [SKIPME
<YES | NO>] [MAXAGE maxage] [NAME name] [IDLE idle] [FLAGS flags]
[LIB-NAME lib-name] [LIB-VER lib-ver] [DB db] [CAPA capa] [IP ip]
[NOT-TYPE <NORMAL | MASTER | REPLICA | PUBSUB>] [NOT-ID not-client-id
[not-client-id...]]  [NOT-USER not-username] [NOT-ADDR ip:port]
[NOT-LADDR ip:port] [NOT-NAME not-name] [NOT-FLAGS not-flags]
[NOT-LIB-NAME not-lib-name] [NOT-LIB-VER not-lib-ver] [NOT-DB not-db]
[NOT-CAPA not-capa] [NOT-IP not-ip]

💅 DESCRIPTION 💅

So CLIENT LIST hands you back info and statistics about the client connections server, in a mostly human readable format. cute, right? but wait — there's more. you can filter that list with one or more optional arguments, and it's giving very much "I know exactly which client I'm looking for" energy. 🔍

here's every single filter, no gatekeeping:

  • TYPE type — filters the list by the clients' type, where type is one of normal, master, replica, and pubsub.
Note: clients blocked by the MONITOR command belong to the normal class. periodt.
  • ID client-id [client-id ...] — returns entries for clients whose IDs match one or more client-id arguments.
  • USER user — only includes clients authenticated as the specified user.
  • ADDR ip:port — only includes clients connected from the specified address and port.
  • LADDR ip:port — only includes clients connected to the specified local address and port.
  • SKIPME yes|no — decides whether the list skips the client making the request.
    • yes: skips the client making the request. 🙈
    • no: includes the client making the request.
  • MAXAGE milliseconds — only includes clients whose connection age (time since the client was created) is greater than or equal to the specified number of milliseconds.
Note: bestie this is actually a minimum age, not a maximum age. it's a whole naming situation 😭 this filter was first added to CLIENT KILL, where the intention was to keep clients of a maximum age and kill the ones newer than the max age.
  • FLAGS flags — filters the list by the client's flag string.
  • NAME name — only includes clients with the specified name.
  • IDLE idle — includes only clients that have been idle for at least the specified time.
  • LIB-NAME lib-name — only includes clients using the specified library name.
  • LIB-VER lib-ver — only includes clients with the specified library version.
  • DB db — only includes clients with the specified database ID.
  • IP ip — only includes clients with the specified IP address.
  • CAPA capa — only includes clients with the specified capabilities.
  • NOT-ID client-id [client-id ...] — excludes clients in the IDs set.
  • NOT-TYPE type — excludes clients of the specified type.
  • NOT-ADDR ip:port — excludes clients of the specified address and port.
  • NOT-LADDR ip:port — excludes clients connected to the specified local address and port.
  • NOT-USER user — excludes clients of the specified user.
  • NOT-FLAGS flags — excludes clients with the specified flag string.
  • NOT-NAME name — excludes clients with the specified name.
  • NOT-LIB-NAME lib-name — excludes clients using the specified library name.
  • NOT-LIB-VER lib-ver — excludes clients with the specified library version.
  • NOT-DB db — excludes clients with the specified database ID.
  • NOT-CAPA capa — excludes clients with the specified capabilities.
  • NOT-IP ip — excludes clients with the specified IP address.

filters can be combined to perform more precise searches 🎯 — the command handles multiple filters via logical AND. so they all gotta match, no exceptions.

🦋 the fields, explained 🦋

here's what every field actually means, iykyk:

  • id: a unique 64-bit client ID
  • addr: address/port of the client
  • laddr: address/port of local address client connected to (bind address)
  • fd: file descriptor corresponding to the socket
  • name: the name set by the client with valkey-client-setname(7) CLIENT SETNAME
  • age: total duration of the connection in seconds
  • idle: idle time of the connection in seconds
  • flags: client flags (see below)
  • capa: client capabilities (see below). added in Valkey 8.1
  • db: current database ID
  • sub: number of channel subscriptions
  • psub: number of pattern matching subscriptions
  • ssub: number of shard channel subscriptions.
  • multi: number of commands in a MULTI/EXEC context
  • watch: number of keys this client is currently watching. added in Valkey 8.0
  • qbuf: query buffer length (0 means no query pending)
  • qbuf-free: free space of the query buffer (0 means the buffer is full)
  • argv-mem: incomplete arguments for the next command (already extracted from query buffer)
  • multi-mem: memory is used up by buffered multi commands.
  • obl: output buffer length
  • oll: output list length (replies are queued in this list when the buffer is full)
  • omem: output buffer memory usage
  • tot-mem: total memory consumed by this client in its various buffers
  • events: file descriptor events (see below)
  • cmd: last command played
  • user: the authenticated username of the client
  • redir: client id of current client tracking redirection
  • resp: client RESP protocol version.
  • lib-name: the client library name as set by valkey-client-setinfo(7) CLIENT SETINFO
  • lib-version: the client library version as set by CLIENT SETINFO
  • tot-net-in: total network input bytes read from this client. added in Valkey 8.0
  • tot-net-out: total network output bytes sent to this client. added in Valkey 8.0
  • tot-cmds: total count of commands this client executed. added in Valkey 8.0

🌈 the client flags 🌈

the client flags can be a combination of:

A: connection to be closed ASAP
b: the client is waiting in a blocking operation
c: connection to be closed after writing entire reply
d: a watched keys has been modified - EXEC will fail
e: the client is excluded from the client eviction mechanism
i: the client is waiting for a VM I/O (deprecated)
M: the client is a primary
N: no specific flag set
O: the client is a client in MONITOR mode
P: the client is a Pub/Sub subscriber
r: the client is in readonly mode against a cluster node
S: the client is a replica node connection to this instance
u: the client is unblocked
U: the client is connected via a Unix domain socket
x: the client is in a MULTI/EXEC context
t: the client enabled keys tracking in order to perform client side caching
T: the client will not touch the LRU/LFU of the keys it accesses
R: the client tracking target client is invalid
B: the client enabled broadcast tracking mode
I: the client is an import source

client's capabilities can be:

r: the client can handle redirect messages

the file descriptor events can be:

r: the client socket is readable (event loop)
w: the client socket is writable (event loop)

🎀 REPLY 🎀

valkey-protocol(7) Bulk string reply: information and statistics about client connections. 💌

👑 COMPLEXITY 👑

O(N) where N is the number of client connections. yeah bestie, it scales with how many friends are in the group chat.

⭐ ACL CATEGORIES ⭐

@admin @connection @dangerous @slow

🧚 HISTORY 🧚

  • Available since: 2.4.0
  • Changed in 2.8.12: added unique client id field.
  • Changed in 5.0.0: added optional TYPE filter.
  • Changed in 6.0.0: added user field.
  • Changed in 6.2.0: added argv-mem, tot-mem, laddr and redir fields and the optional ID filter.
  • Changed in 7.0.0: added resp, multi-mem, rbs and rbp fields.
  • Changed in 7.0.3: added ssub field.
  • Changed in 8.0.0: replaced master TYPE with primary. master still supported for backward compatibility.
  • Changed in 8.1.0: added filters USER, ADDR, LADDR, SKIPME, and MAXAGE.
  • Changed in 9.0.0: added filters NAME, IDLE, FLAGS, LIB-NAME, LIB-VER, DB, CAPA, and IP. and negative filters NOT-ID, NOT-TYPE, NOT-ADDR, NOT-LADDR, NOT-USER, NOT-FLAGS, NOT-NAME, NOT-LIB-NAME, NOT-LIB-VER, NOT-DB, NOT-CAPA, NOT-IP.

🍓 EXAMPLES 🍓

CLIENT LIST TYPE normal USER admin MAXAGE 5000 ID 1234 5678
id=1234 addr=127.0.0.1:64000 laddr=127.0.0.1:6379 fd=5 name= age=600 idle=300 flags= db=0 sub=0 psub=0 ssub=0 multi=-1 watch=0 qbuf=0 qbuf-free=32768 obl=0 oll=0 omem=0 tot-mem=1024 events=r cmd=client|list user=default redir=-1 resp=2 lib-name= lib-ver=
id=5678 addr=127.0.0.1:64001 laddr=127.0.0.1:6379 fd=6 name= age=900 idle=450 flags= db=0 sub=0 psub=0 ssub=0 multi=-1 watch=0 qbuf=0 qbuf-free=32768 obl=0 oll=0 omem=0 tot-mem=2048 events=r cmd=client|list user=default redir=-1 resp=2 lib-name= lib-ver=

💜 NOTES 💜

new fields are regularly added for debugging purpose. some could be removed in the future. so a version safe Valkey client using this command should parse the output accordingly — meaning handle missing fields gracefully and skip unknown fields. don't be rigid, bestie, be flexible. 🫶

🌸 SEE ALSO 🌸

auth(3valkey), client(3valkey), client-caching(3valkey), client-capa(3valkey), client-getname(3valkey), client-getredir(3valkey), client-help(3valkey), client-id(3valkey), client-import-source(3valkey), client-info(3valkey), client-kill(3valkey), client-no-evict(3valkey), client-no-touch(3valkey), client-pause(3valkey), client-reply(3valkey), client-setinfo(3valkey), client-setname(3valkey), client-tracking(3valkey), client-trackinginfo(3valkey), client-unblock(3valkey), client-unpause(3valkey), echo(3valkey), hello(3valkey), ping(3valkey), quit(3valkey), reset(3valkey), select(3valkey)

and that's a wrap, gorgeous 💖 this was CLIENT-LIST(3valkey) from Valkey 9.0.0, dated 2025-10-21 — now go forth and list those connections, main character. ✨👑

📦 where this page comes from