Regis Quick Start Guide

The User Interface

The main Regis interface.
The main Regis interface.

Regis uses a convenient multi-window, multi-tabs main user interface. The typical shortcuts are available to manage windows and tabs: ⌘T opens a new tab, ⌘N opens a new window, ⌘W closes the current tab, ⌘⇧W closes the current window. Each tab is an independent Redis session and has the same layout.

At the bottom is the Command Box where commands are typed. It can be resized using the Resize Bar. The Prompt indicates the current mode - typically, the > prompt is displayed, but when a connection is in pipeline, pub-sub or monitor mode, it is reflected in the prompt.

The upper part, by default the main part of the screen, is the Output Section. This is where the results of the commands are displayed. Most commands produce a result, and those results are listed here, in a scrollable list so that old results can still be viewed after other commands have been executed.

The Execute Button executes the command typed in the Command Box. It turns blue when a valid command is ready to be executed. The button remains disabled while the command is running, but otherwise the interface is not blocked. The ⌘⏎ shortcut can be used instead of clicking on the button.

The Output Filter text box filters the displayed results. The Edit→Filter menu item (shortcut: ⌘F) moves the focus to this text box.

Connecting To Redis

Connecting to a Redis host.
Connecting to a Redis host.

To connect to a Redis host, use the built-in command \CONNECT host:port. If you don’t have Redis installed locally, you can easily install it using Homebrew:

$ brew install redis

And then you can start a local instance (by default, it runs on port 6379, but you can specify a --port 1234 flag to use another port):

$ redis-server

Once you have an instance running, come back to Regis and execute the \CONNECT localhost:6379 command (adjust port number as needed). You should now be connected.

You may be wondering why you need to type a backslash (\) in front of the command. All built-in commands start with a backslash, to differentiate them from standard Redis commands (in order to avoid a conflict when new Redis commands are added). The backslash was chosen because it is the typical escape character in many programming languages.

You can try running some Redis commands. For example, type:

> set key_1 hello

You should see the OK reply in the output. If you execute:

> get key_1

You will get back the content of that key. Play a bit with the result to see the various ways you can display the value.

Retrieving the value of a key.
Retrieving the value of a key.

Now say you want to set the key to “hello, world”. One way to try to do it may be:

> set key_1 hello, world

But that won’t work, you’ll get a syntax error. That’s because the Redis SET command expects a key and a value, and 2 values were provided (“hello,” and “world”). To send multiple words in a single parameter, use quotes:

> set key_1 "hello, world"

That should work. Try to GET back the value to make sure it was properly set.

To disconnect from Redis, execute \DISCONNECT (or simply close the tab).

If you want to connect to a Redis host that is not available from your computer, see connecting via an SSH tunnel in the documentation.

Executing Commands

Executing commands.
Executing commands.

Once connected, standard Redis commands can be executed, in addition to built-in commands. The output is adapted to the type of the result - for instance, in the screenshot above, the INFO command is parsed and displayed in a convenient hierarchical table. Each output has a single-line, compact result and most also have an expanded view with additional features depending on the result.

As seen in the previous section, Redis values can be viewed as JSON and Redis strings (bytes, really) can also be viewed as hexadecimal, base64-encoded or binary (zeros and ones). Built-in commands such as \SCANKEYS display a table of matching keys along with their type, and you can select and delete a batch of keys from its output view.

Some results have nested scrolling, for example if a result displays a table with lots of rows, that table will scroll, making it hard to scroll through the output section. On either side of the screen, there’s a gutter that is outside any results view (located below the disclosure triangle used to expand or collapse a result, and the same size on the other side of the screen). Scrolling in this location will always scroll the output section. You can also use Edit→Clear Output (shortcut: ⌘K) to clear all results.

Session Settings

The session settings panel.
The session settings panel.

Each tab starts with the default session settings (remember, each tab is an independent session). Those defaults are generally sane and safe, but before connecting to a production server, it’s a good idea to review them and adjust them as needed. The settings panel is accessed via the Session→Settings... menu item, or with the ⌘< shortcut.

Commands can be blacklisted so that they can’t be executed by the user. It is also possible to whitelist specific commands, in which case only those whitelisted commands can be executed by the user.

If you expect to connect often to a specific host, you should save the settings so you don’t have to change them each time. Saved settings can be loaded by the \LOADSESSION name built-in command. This will apply the settings, connect to the host if the session was connected when the settings were saved, and automatically authenticate to the Redis server if the session was authenticated when it was saved. Redis passwords are securely stored in the local Mac Keychain.

Tabs & Windows

Multiple tabs and windows.
Multiple tabs and windows.

As mentioned earlier, you can open multiple windows and multiple tabs per window. Each tab is an independent Redis session. Sometimes it can be useful to open a new tab or window using the same settings and connection as the current one (for example, if the current session is subscribed to a channel, and you want to post to that channel).

The File→New Tab with Current Session menu item (shortcut: ⌘⇧T) does exactly that, and the File→New Window with Current Session menu item (shortcut: ⌘⇧N) does the same in a new window.

The sessions are still independent (changing a setting in one won’t affect the other), but the new tab or window is initially configured as the original one and is automatically connected (and authenticated, if required) to the same Redis host.

And More

This should be enough to get started with Regis, but there’s much more to it:

See the documentation for more.