# CLIENT LIST

> List client connections, one line of fields each, optionally filtered by type, flags or id.

URL: https://docs.hotkv.com/commands/client-list/

```
CLIENT LIST [TYPE NORMAL | MASTER | REPLICA | PUBSUB] [FLAGS flags] [ID client-id [client-id ...]]
```

- Group: Connection
- Complexity: O(N) where N is the number of client connections
- HotKV Cloud: all plans
- On-Premise: no license needed

`CLIENT LIST` returns one line per client connection, each made of
space-separated `field=value` pairs. Use it to find idle or misbehaving
clients, see which user and database each connection uses, spot clients with
large unread replies, and see which clients hold the most memory.

## Options

| Option | Effect |
| --- | --- |
| `TYPE type` | Only connections of this type. `normal` is a regular client, `pubsub` a subscribed one, `replica` the connection of a replica (`slave` is taken as `replica`), and `master` this node's own link to its primary, when it is a replica. |
| `FLAGS flags` | Only connections that have every flag letter given, for example `FLAGS tB`. |
| `ID client-id [client-id ...]` | Only these connection ids. `ID` takes every argument after it. |

The options can be combined, in any order; a connection must match all of them.

Errors: `ERR Unknown client type '<type>'`, `ERR Invalid client ID` for an id
that is not an integer, and `ERR syntax error` for anything else.

## Fields

| Field | Meaning |
| --- | --- |
| `id` | Connection id, see [CLIENT ID](https://docs.hotkv.com/commands/client-id/index.md). |
| `addr` | Client address and port. |
| `laddr` | Local address and port the client connected to. |
| `fd` | Socket file descriptor. |
| `name` | Name set with [CLIENT SETNAME](https://docs.hotkv.com/commands/client-setname/index.md), empty if none. |
| `age` | Seconds since the connection was opened. |
| `idle` | Seconds since its last command. |
| `flags` | One or more letters, see below. |
| `db` | Selected database. |
| `sub`, `psub`, `ssub` | Channel, pattern and shard channel subscriptions. |
| `multi` | Commands queued in an open transaction, or `-1` outside one. |
| `watch` | Keys watched with [WATCH](https://docs.hotkv.com/commands/watch/index.md). |
| `qbuf` | Bytes of input received and not run yet. For a large argument that is still arriving, the part that has come. |
| `qbuf-free` | Room left in the input buffer: what the buffer holds less the input and the arguments parsed so far. |
| `argv-mem` | Bytes of the arguments of the command being read that are already parsed. |
| `multi-mem` | Bytes of the commands queued by `MULTI`. |
| `omem` | Bytes of replies and pushes not yet sent to the client. |
| `tot-mem` | The memory [`maxmemory-clients`](https://docs.hotkv.com/reference/configuration/index.md#maxmemory-clients) counts for this client. See [Client memory](https://docs.hotkv.com/operate/memory-and-eviction/index.md#client-memory). |
| `cmd` | Last command run, in lower case, with its subcommand (`client\|list`), or `NULL`. |
| `user` | ACL user of the connection. |
| `redir` | `-1` when [client-side caching](https://docs.hotkv.com/develop/client-side-caching/index.md) tracking is off, `0` when its invalidations come to this connection, else the id of the connection they are redirected to. |
| `resp` | Protocol version, `2` or `3`. |
| `lib-name`, `lib-ver` | Set with [CLIENT SETINFO](https://docs.hotkv.com/commands/client-setinfo/index.md). |

For compatibility with tools that parse Redis's output, the line also has
`rbs`, `rbp`, `obl` and `oll`, which are always `0`, and `events`, which is always
`r`.

Flags:

| Flag | Meaning |
| --- | --- |
| `N` | None of the others. |
| `S` | The connection of a replica, for this node as its primary. |
| `M` | This node's link to its primary, when it is a replica. |
| `P` | Subscribed to channels or patterns. |
| `x` | In a transaction. |
| `b` | Blocked in a blocking command. |
| `t` | [Client-side caching](https://docs.hotkv.com/develop/client-side-caching/index.md) tracking is on. |
| `B` | Tracking in `BCAST` mode. |
| `R` | Tracking, and the connection its invalidations were redirected to is gone. |
| `d` | A watched key changed (the transaction will fail). |
| `c` | Closing after the current reply. |
| `r` | `READONLY` cluster connection. |
| `e` | [CLIENT NO-EVICT](https://docs.hotkv.com/commands/client-no-evict/index.md) on. |
| `T` | [CLIENT NO-TOUCH](https://docs.hotkv.com/commands/client-no-touch/index.md) on. |
| `I` | Another cluster node's own connection. |
| `i`, `o`, `E` | Connections of an atomic slot migration: `i` and `o` import connections (Valkey 9's and Redis 8's), `E` one this node exports on. |

A client that holds more than `maxmemory-clients` and may be evicted is not
listed, from the moment it grows past the limit.

## Return value

The lines, each ending with a newline: a bulk string in RESP2, a verbatim
string (`txt`) in RESP3. An empty string when no connection matches.

## Examples

```
127.0.0.1:6379> CLIENT LIST
id=93 addr=127.0.0.1:33610 laddr=127.0.0.1:6379 fd=39 name=reporting age=2 idle=0 flags=N db=0 sub=0 psub=0 ssub=0 multi=-1 watch=0 qbuf=0 qbuf-free=256 argv-mem=0 multi-mem=0 rbs=0 rbp=0 obl=0 oll=0 omem=0 tot-mem=1208 events=r cmd=client|list user=default redir=-1 resp=2 lib-name= lib-ver=
id=94 addr=127.0.0.1:33622 laddr=127.0.0.1:6379 fd=40 name= age=2 idle=2 flags=P db=0 sub=1 psub=0 ssub=0 multi=-1 watch=0 qbuf=0 qbuf-free=256 argv-mem=0 multi-mem=0 rbs=0 rbp=0 obl=0 oll=0 omem=0 tot-mem=1272 events=r cmd=subscribe user=default redir=-1 resp=2 lib-name=redis-py lib-ver=8.1.0
id=95 addr=127.0.0.1:33626 laddr=127.0.0.1:6379 fd=41 name=cache age=1 idle=0 flags=tB db=0 sub=0 psub=0 ssub=0 multi=-1 watch=0 qbuf=0 qbuf-free=256 argv-mem=0 multi-mem=0 rbs=0 rbp=0 obl=0 oll=0 omem=0 tot-mem=1224 events=r cmd=client|tracking user=default redir=0 resp=3 lib-name= lib-ver=
127.0.0.1:6379> CLIENT LIST TYPE pubsub
id=94 addr=127.0.0.1:33622 laddr=127.0.0.1:6379 fd=40 name= age=2 idle=2 flags=P db=0 sub=1 psub=0 ssub=0 multi=-1 watch=0 qbuf=0 qbuf-free=256 argv-mem=0 multi-mem=0 rbs=0 rbp=0 obl=0 oll=0 omem=0 tot-mem=1272 events=r cmd=subscribe user=default redir=-1 resp=2 lib-name=redis-py lib-ver=8.1.0
127.0.0.1:6379> CLIENT LIST FLAGS tB
id=95 addr=127.0.0.1:33626 laddr=127.0.0.1:6379 fd=41 name=cache age=1 idle=0 flags=tB db=0 sub=0 psub=0 ssub=0 multi=-1 watch=0 qbuf=0 qbuf-free=256 argv-mem=0 multi-mem=0 rbs=0 rbp=0 obl=0 oll=0 omem=0 tot-mem=1224 events=r cmd=client|tracking user=default redir=0 resp=3 lib-name= lib-ver=
127.0.0.1:6379> CLIENT LIST TYPE robot
(error) ERR Unknown client type 'robot'
```

## Compatibility

The line has the fields of Redis 7's `CLIENT LIST`, in the same order. `rbs`,
`rbp`, `obl`, `oll` and `events` are fixed, and the flags `I`, `i`, `o` and `E`
show the cluster's own connections. The `FLAGS` option is Valkey 9's.

## See also

[CLIENT INFO](https://docs.hotkv.com/commands/client-info/index.md), [CLIENT KILL](https://docs.hotkv.com/commands/client-kill/index.md),
[CLIENT SETNAME](https://docs.hotkv.com/commands/client-setname/index.md), [CLIENT NO-EVICT](https://docs.hotkv.com/commands/client-no-evict/index.md),
[CLIENT TRACKINGINFO](https://docs.hotkv.com/commands/client-trackinginfo/index.md), [INFO](https://docs.hotkv.com/commands/info/index.md)