# hotkv-cli

> The command-line client that ships with HotKV, its options, authentication, TLS, and how it compares with redis-cli.

URL: https://docs.hotkv.com/get-started/hotkv-cli/


`hotkv-cli` is the command-line client installed with the HotKV server. It
runs one command and exits, or opens an interactive prompt. It speaks the
same protocol as `redis-cli`, so it works against Redis and Valkey servers
too, and `redis-cli` and `valkey-cli` work against HotKV.

## Run a command

Give the command after the options. The reply is printed and the exit
status is `0`, or `1` when the reply is an error or the client could not
connect, so scripts can test it:

```bash
hotkv-cli SET greeting "hello"
# OK
hotkv-cli GET greeting
# "hello"
hotkv-cli -h db.internal -p 6380 INCR visits
```

When the output goes to a terminal, replies are formatted with their type,
as `redis-cli` shows them: `(integer) 1`, `(nil)`, `(error) ...`, quoted
strings and numbered arrays. When the output is a pipe or a file, only the
bare values are printed, one per line. `--raw` forces bare values and
`--no-raw` forces the formatted output.

## Interactive prompt

Without a command, `hotkv-cli` opens a prompt that shows the host and port
(and the database, when it is not 0):

```
$ hotkv-cli
127.0.0.1:6379> SET user:1 "Ada Lovelace"
OK
127.0.0.1:6379> GET user:1
"Ada Lovelace"
127.0.0.1:6379> quit
```

Arguments are separated by spaces. Put an argument in double quotes to
include spaces, with `\n`, `\r`, `\t`, `\"` and `\\` escapes, or in single
quotes to take it literally. Besides server commands the prompt knows
`help`, `clear` (clear the screen) and `quit` or `exit`.

## Options

| Option | Default | Description |
| --- | --- | --- |
| `-h`, `--host HOST` | `127.0.0.1` | Server host name or address |
| `-p`, `--port PORT` | `6379` | Server port |
| `-a`, `--auth PASSWORD` | | Password to authenticate with |
| `--user NAME` | | ACL user to authenticate as, with the password |
| `-n`, `--db N` | `0` | Database to select after connecting |
| `-u`, `--uri URI` | | Connection URI (see below) |
| `--tls` | off | Connect with TLS |
| `--sni NAME` | the host | Name to send with SNI and to verify in the server certificate |
| `--cacert FILE` | | CA certificate to verify the server with |
| `--cacertdir DIR` | | Directory of CA certificates to verify the server with |
| `--cert FILE` | | Client certificate, for servers that require one |
| `--key FILE` | the `--cert` file | Private key for `--cert` |
| `--insecure` | off | Do not verify the server certificate |
| `--raw` | | Print bare values |
| `--no-raw` | | Print formatted replies even into a pipe |
| `-v`, `--version` | | Print the version and exit |
| `--help` | | Print the options and exit |

Note that `-h` is the host, not help, as in `redis-cli`.

## Authentication

With `-a`, the client sends `AUTH` right after connecting; with `--user`
too, it sends `AUTH user password` for an [ACL user](https://docs.hotkv.com/operate/acl/index.md):

```bash
hotkv-cli -a "$PASSWORD" PING
hotkv-cli --user reports -a "$REPORTS_PASSWORD" GET report:2026-09
```

A password given with `-a` is visible to other users of the machine in the
process list. Set the `HOTKVCLI_AUTH` environment variable instead, and
`hotkv-cli` uses it whenever no password is given on the command line:

```bash
export HOTKVCLI_AUTH='your-password'
hotkv-cli PING
```

If authentication fails, `hotkv-cli` prints `AUTH failed:` with the
server's reason on standard error and carries on, so the commands that
follow get a `NOAUTH` error from a server that requires a password.

## Connection URIs

`-u` takes the connection as one string:

```
hotkv://[[user]:password@]host[:port][/db]
hotkvs://[[user]:password@]host[:port][/db]
```

`hotkvs://` turns on TLS. The `redis://` and `rediss://` schemes are
accepted too, so a URI from an existing Redis setup works as it is. Special
characters in the user name or password can be percent-encoded. Options
given explicitly win over the parts of the URI:

```bash
hotkv-cli -u "hotkvs://:$PASSWORD@db.example.com:6380/2" DBSIZE
hotkv-cli -u "hotkv://app:$APP_PASSWORD@10.0.0.5:6379" -n 3 PING   # database 3
```

## TLS

`--tls` connects with TLS 1.2 or later. By default the server certificate
must be signed by a CA in the system's CA store and must name the host you
connect to (its DNS name, or its IP address when you connect by address).

```bash
# Server with a publicly trusted certificate (such as HotKV Cloud)
hotkv-cli --tls -h <host> -p <port> PING

# Your own CA, and a client certificate for mutual TLS
hotkv-cli --tls -h db.internal -p 6380 \
  --cacert /etc/hotkv/tls/ca.crt \
  --cert /etc/hotkv/tls/client.crt --key /etc/hotkv/tls/client.key PING

# Connecting by address, verifying the name the certificate was issued for
hotkv-cli --tls -h 10.0.0.5 -p 6380 --sni db.internal --cacert ca.crt PING
```

`--insecure` skips certificate verification. Use it for testing only: it
does not protect against someone impersonating the server. See
[TLS](https://docs.hotkv.com/operate/tls/index.md) for the server side.

## Compared with redis-cli

The common options have the same names as in `redis-cli`: `-h`, `-p`, `-a`,
`--user`, `-n`, `-u`, `--tls`, `--sni`, `--cacert`, `--cacertdir`,
`--cert`, `--key`, `--insecure`, `--raw` and `--no-raw`. `HOTKVCLI_AUTH`
plays the part of `REDISCLI_AUTH`.

`hotkv-cli` is a simpler client and does not have these `redis-cli`
features:

- cluster mode (`-c`): it does not follow `MOVED` and `ASK` redirects, so
  connect to the node that holds the key, or use `redis-cli -c` (see the
  [cluster quick start](https://docs.hotkv.com/clustering/quick-start/index.md#5-what-hotkv-cli-does));
- RESP3 output (`-3`): replies are formatted as RESP2, so stay on the
  default protocol and do not switch the connection with `HELLO 3`;
- reading an argument from standard input (`-x`), repeating commands
  (`-r`, `-i`), mass insert (`--pipe`), and the scanning and monitoring
  modes (`--scan`, `--bigkeys`, `--memkeys`, `--latency`, `--stat`);
- Unix sockets (`-s`), which HotKV does not listen on;
- line editing, history and command hints at the prompt.

> **Tip**
> For any of these, use `redis-cli` or `valkey-cli`: they work against HotKV
> with the same host, port, password and TLS options.

## Next steps

- [Security](https://docs.hotkv.com/security/index.md) and [ACL](https://docs.hotkv.com/operate/acl/index.md): passwords and users.
- [TLS](https://docs.hotkv.com/operate/tls/index.md): certificates on the server.
- [Command reference](https://docs.hotkv.com/commands/index.md): every command you can run.