===

A CLI for DiceDB with auto completion and syntax highlighting.

$ python -m venv venv
$ . venv/bin/activate
$ pip install -e .

dice is a terminal client for redis with auto-completion and syntax highlighting. dice lets you type Redis commands smoothly, and displays results in a user-friendly format.

dice is an alternative for redis-cli. In most cases, dice behaves exactly the same as redis-cli. Besides, it is safer to use dice on production servers than redis-cli: dice will prevent accidentally running dangerous commands, like KEYS * (see Redis docs / Latency generated by slow commands).

• Advanced code completion. If you run command KEYS then run DEL, dice will auto-complete your command based on KEYS result.
• Command validation. dice will validate command while you are typing, and highlight errors. E.g. try CLUSTER MEET IP PORT, dice will validate IP and PORT for you.
• Command highlighting, fully based on redis grammar. Any valid command in dice shell is a valid redis command.
• Human-friendly result display.
• pipeline feature, you can use your favorite shell tools to parse redis' response, like get json | jq ..
• Support pager for long output.
• Support connection via URL, dice --url redis://example.com:6379/1.
• Support cluster, dice will auto reissue command for MOVED response in cluster mode.
• Store server configuration: dice -d prod-redis (see dsn for more).
• peek command to check the key's type then automatically call get/lrange/sscan, etc, depending on types. You don't need to call the type command then type another command to get the value. peek will also display the key's length and memory usage.
• Ctrl + C to cancel the current typed command, this won't exit dice, exactly like bash behaviour. Use Ctrl + D to send a EOF to exit dice.
• Ctrl + R to open reverse-i-search to search through your command history.
• Auto suggestions. (Like fish shell.)
• Support --encode=utf-8, to decode Redis' bytes responses.
• Command hint on bottom, include command syntax, supported redis version, and time complexity.
• Official docs with built-in HELP command, try HELP SET!
• Written in pure Python, but dice was packaged into a single binary with PyOxidizer, you can use cURL to download and run, it just works, even you don't have a Python interpreter.
• You can change the cli prompt using --prompt option or set via ~/.dicerc config file.
• Hide password for AUTH command.
• Says "Goodbye!" to you when you exit!
• For full features, please see: dice.xbin.io

Install via pip:

pip install dice

pipx is recommended:

pipx install dice

For Mac users, you can install dice via brew 🍻

brew install dice

You can also use your Linux package manager to install dice, like apt in Ubuntu (Only available on Ubuntu 21.04+).

apt install dice

Or you can download the executable binary with cURL(or wget), untar, then run. It is especially useful when you don't have a python interpreter(E.g. the official Redis docker image which doesn't have Python installed.):

wget  https://github.com/dicedb/cli/releases/latest/download/dice.tar.gz \
 && tar -xzf dice.tar.gz \
 && ./dice

(Check the release page if you want to download an old version of dice.)

Once you install dice, you will know how to use it. Just remember, dice supports similar options like redis-cli, like -h for redis-server's host and -p for port.

$ dice --help

Usage: dice [OPTIONS] [CMD]...

  dice: Interactive Redis

  When no command is given, dice starts in interactive mode.

  Examples:
    - dice
    - dice -d dsn
    - dice -h 127.0.0.1 -p 6379
    - dice -h 127.0.0.1 -p 6379 -a <password>
    - dice --url redis://localhost:7890/3

  Type "help" in interactive mode for information on available commands and
  settings.

Options:
  -h TEXT                         Server hostname (default: 127.0.0.1).
  -p TEXT                         Server port (default: 6379).
  -s, --socket TEXT               Server socket (overrides hostname and port).
  -n INTEGER                      Database number.(overwrites dsn/url's db
                                  number)

  -u, --username TEXT             User name used to auth, will be ignore for
                                  redis version < 6.

  -a, --password TEXT             Password to use when connecting to the
                                  server.

  --url TEXT                      Use Redis URL to indicate connection(Can set
                                  with env `dice_URL`), Example:     redis:/
                                  /[[username]:[password]]@localhost:6379/0
                                  rediss://[[username]:[password]]@localhost:6
                                  379/0     unix://[[username]:[password]]@/pa
                                  th/to/socket.sock?db=0

  -d, --dsn TEXT                  Use DSN configured into the [alias_dsn]
                                  section of dicerc file. (Can set with env
                                  `dice_DSN`)

  --newbie / --no-newbie          Show command hints and useful helps.
  --dicerc TEXT                 Config file for dice, default is
                                  ~/.dicerc.

  --decode TEXT                   decode response, default is No decode, which
                                  will output all bytes literals.

  --client_name TEXT              Assign a name to the current connection.
  --raw / --no-raw                Use raw formatting for replies (default when
                                  STDOUT is not a tty). However, you can use
                                  --no-raw to force formatted output even when
                                  STDOUT is not a tty.

  --rainbow / --no-rainbow        Display colorful prompt.
  --shell / --no-shell            Allow to run shell commands, default to
                                  True.

  --pager / --no-pager            Using pager when output is too tall for your
                                  window, default to True.

  --verify-ssl [none|optional|required]
                                  Set the TLS certificate verification
                                  strategy

  --prompt TEXT                   Prompt format (supported interpolations:
                                  {client_name}, {db}, {host}, {path}, {port},
                                  {username}, {client_addr}, {client_id}).

  --version                       Show the version and exit.
  --help                          Show this message and exit.

dice support storing server configuration in config file. Here is a DSN config:

[alias_dsn]
dev=redis://localhost:6379/4
staging=redis://username:password@staging-redis.example.com:6379/1

Put this in your dicerc then connect via dice -d staging or dice -d dev.

You can change the prompt str, the default prompt is:

127.0.0.1:6379>

Which is rendered by {host}:{port}[{db}]> , you can change this via --prompt option or change dicerc config file. The prompwt string uses python string format engine, supported interpolations:

• {client_name}
• {db}
• {host}
• {path}
• {port}
• {username}
• {client_addr}
• {client_id}

The --prompt utilize Python String format engine, so as long as it is a valid string formatter, it will work( anything that "<your prompt>".format(...) accepts). For example, you can limit your Redis server host name's length to 5 by setting --prompt to dice --prompt '{host:.5s}'.

dice supports config files. Command-line options will always take precedence over config. Configuration resolution from highest to lowest precedence is:

• Options from command line
• $PWD/.dicerc
• ~/.dicerc (this path can be changed with dice --dicerc $YOUR_PATH)
• /etc/dicerc
• default config in dice package.

You can copy the self-explained default config here:

https://raw.githubusercontent.com/dicedb/cli/master/dice/data/dicerc

And then make your own changes.

(If you are using an old versions of dice, please use the config file below, and change the version in URL):

https://raw.githubusercontent.com/dicedb/cli/v1.0.4/dice/data/dicerc

dice support unix/readline-style REPL keyboard shortcuts, which means keys like Ctrl + F to forward work.

Also:

• Ctrl + D (i.e. EOF) to exit; you can also use the exit command.
• Ctrl + L to clear screen; you can also use the clear command.
• Ctrl + X Ctrl + E to open an editor to edit command, or V in vi-mode.

dice is built and released by GitHub Actions. Whenever a tag is pushed to the master branch, a new release is built and uploaded to pypi.org, it's very convenient.

Thus, we release as often as possible, so that users can always enjoy the new features and bugfixes quickly. Any bugfix or new feature will get at least a patch release, whereas big features will get a minor release.

dice favors poetry as package management tool. To setup a develop environment on your computer:

First, install poetry (you can do it in a python's virtualenv):

pip install poetry

Then run (which is similar to pip install -e .):

poetry install

Be careful running testcases locally, it may flush you db!!!

This is a command-line tool, so we don't write logs to stdout.

You can tail -f ~/.dice.log to see logs, the log is pretty clear, you can see what actually happens from log files.

dice use a git submodule to track current-up-to-date redis-doc version. To catch up with latest:

1. Git pull in redis-doc
2. Copy doc files to /data: cp -r redis-doc/commands* dice/data
3. Prettier markdownprettier --prose-wrap always dice/data/commands/*.md --write
4. Check the diff, update dice' code if needed.

• redis-tui

If you like dice, you may also like other cli tools by dbcli:

• pgcli - Postgres Client with Auto-completion and Syntax Highlighting
• mycli - MySQL/MariaDB/Percona Client with Auto-completion and Syntax Highlighting
• litecli - SQLite Client with Auto-completion and Syntax Highlighting
• mssql-cli - Microsoft SQL Server Client with Auto-completion and Syntax Highlighting
• athenacli - AWS Athena Client with Auto-completion and Syntax Highlighting
• vcli - VerticaDB client
• dice - Client for Redis with AutoCompletion and Syntax Highlighting

dice is build on the top of prompt_toolkit, a Python library (by Jonathan Slenders) for building rich commandline applications.