RedisInsight Documentation

Technical Documentation: redis/RedisInsight

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Redis Insight - Developer GUI for Redis, by Redis.

Redis Insight is a visual tool that provides capabilities to design, develop, and optimize your Redis application.
Query, analyse and interact with your Redis data. Download it here!

Built with love using Electron, Monaco Editor and NodeJS.

Overview Copy Chapter

Redis Insight is an intuitive and efficient GUI for Redis, allowing you to interact with your databases and manage your data—with built-in support for Redis modules.

Redis Insight Highlights: Copy Section

• Browse, filter, visualise your key-value Redis data structures and see key values in different formats (including JSON, Hex, ASCII, etc.)
• CRUD support for lists, hashes, strings, sets, sorted sets, and streams
• CRUD support for JSON data structure
• CRUD support for vector sets - create and manage vector sets, add elements, and run vector similarity search
• CRUD support for arrays - create, browse, search, aggregate, edit, and delete array elements
• Interactive tutorials to learn easily, among other things, how to leverage the native JSON data structure supporting structured querying and full-text search, including vector similarity search for your AI use cases
• Contextualised recommendations to optimize performance and memory usage. The list of recommendations gets updated as you interact with your database
• Profiler - analyze every command sent to Redis in real-time
• SlowLog - analyze slow operations in Redis instances based on the Slowlog command
• Pub/Sub - support for Redis pub/sub, enabling subscription to channels and posting messages to channels
• Bulk actions - Delete the keys in bulk based on the filters set in Browser or Tree view
• Workbench - advanced command line interface with intelligent command auto-complete, complex data visualizations and support for the raw mode
• Command auto-complete support for search and query capability, JSON and time series data structures
• Visualizations of your search and query indexes and results.
• Vector search - create and manage search indexes and query your indexed data
• Ability to build your own data visualization plugins
• Officially supported for Redis OSS, Redis Cloud. Works with Microsoft Azure Managed Redis (formerly Azure Cache for Redis)

Check out the release notes.

Get started with Redis Insight Copy Chapter

This repository includes the code for Redis Insight. Check out the blogpost announcing it.

Installable Copy Section

Redis Insight is available as a free download redis.io.
You can also find it on the Microsoft Store, Apple App Store, Snapcraft, Flathub, and as a Docker image.

Additionally, you can use Redis for VS Code, our official Visual Studio Code extension.

Build Copy Section

Alternatively you can also build from source. See our wiki for instructions.

• How to build

How to debug Copy Chapter

If you have any issues occurring in Redis Insight, you can follow the steps below to get more information about the errors and find their root cause.

• How to debug

Redis Insight API (only for Docker) Copy Chapter

If you are running Redis Insight from Docker, you can access the API from http://localhost:5540/api/docs.

Azure Managed Redis (formerly Azure Cache for Redis) Copy Chapter

Redis Insight supports Azure Managed Redis and Azure Cache for Redis with Microsoft Entra ID authentication. If your organization requires admin consent for third-party applications, see our setup guide.

• Azure Setup Guide
• Azure Docker Setup - Configuration for Docker, custom ports, and reverse proxies

Feedback Copy Chapter

• Request a new feature
• Upvote popular feature requests
• File a bug

Redis Insight Plugins Copy Chapter

With Redis Insight you can now also extend the core functionality by building your own data visualizations. See our wiki for more information.

• Plugin Documentation

Contributing Copy Chapter

If you would like to contribute to the code base or fix and issue, please consult the wiki.

• How to build and contribute

API documentation Copy Chapter

If you're using a Docker image of Redis Insight, open this URL to view the list of APIs:
http://localhost:5530/api/docs

Telemetry Copy Chapter

Redis Insight includes an opt-in telemetry system, that is leveraged to help improve the developer experience (DX) within the app. We value your privacy, so stay assured, that all the data collected is anonymised.

License Copy Chapter

Redis Insight is licensed under SSPL license.

Overview (`.ai/README.md`) Copy Section

RedisInsight AI Development Rules

This directory contains the single source of truth for AI-assisted development rules and workflows in RedisInsight.

Overview Copy Chapter

This repository uses a centralized approach to AI development rules:

• AGENTS.md (at repository root) - Entry point for AI agents with essential commands, testing instructions, and quick reference
• .ai/skills/ - Detailed development standards as skills, plus skills from npm packages
• .ai/commands/ - AI workflow commands and templates

These standards are consumed by:

• Claude Code (via CLAUDE.md -> AGENTS.md plus .claude/commands/ and .claude/skills/ symlinks)
• Codex (via AGENTS.md and the .agents/skills symlink)
• GitHub Copilot (via file: .github/copilot-instructions.md, optional)

Structure Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Codex note: Codex reads AGENTS.md for project instructions and discovers repo skills from .agents/skills. Do not create .codex/rules/: Codex .rules files are command execution policies, not Markdown development guidelines.

For AI Agents Copy Chapter

Start here: Read AGENTS.md at the repository root for:

• Setup and build commands
• Code quality standards
• Testing instructions
• Git workflow guidelines
• Boundaries and best practices

Then refer to: .ai/skills/ for detailed guidelines on specific topics.

For Human Developers Copy Chapter

This directory contains comprehensive development standards used by AI coding assistants. Each topic lives in its own skill folder:

• Code Quality: .ai/skills/code-quality/SKILL.md - TypeScript standards, import organization, best practices
• Frontend: .ai/skills/frontend/SKILL.md - React, Redux, styled-components, UI component usage
• Backend: .ai/skills/backend/SKILL.md - NestJS, dependency injection, API patterns
• Testing: .ai/skills/testing/SKILL.md - Jest/Testing Library patterns, faker, helpers
• E2E Testing: .ai/skills/e2e-testing/SKILL.md - Playwright standards, page objects
• Git Safety: .ai/skills/git-safety/SKILL.md - Protected-branch guardrails
• Branches: .ai/skills/branches/SKILL.md - Branch naming conventions
• Commits: .ai/skills/commits/SKILL.md - Commit message guidelines (Conventional Commits)
• Pull Requests: .ai/skills/pull-requests/SKILL.md - PR creation and review guidelines
• Feature Flags: .ai/skills/feature-flags/SKILL.md - Adding, promoting, and removing feature flags
• TS Error Baselines: .ai/skills/type-check-baselines/SKILL.md - TypeScript error baseline workflow
• Redis UI Components: .ai/skills/redis-ui-components/ - Component API references, props, and usage examples (sourced from @redis-ui/components npm package via symlink)

MCP (Model Context Protocol) Setup Copy Chapter

AI tools can access external services (JIRA, Confluence, GitHub, Figma) via MCP configuration.

Initial Setup Copy Section

1. Copy the example configuration:

   bash Copy

   cp env.mcp.example .env.mcp

2. Get your Atlassian API token:

   • Go to: https://id.atlassian.com/manage-profile/security/api-tokens
   • Create a classic token by pressing the first "Create Token" button
   • Copy the token

3. Edit .env.mcp with your credentials:

   • Add your JIRA and Confluence API tokens
   • Note: Figma MCP server uses OAuth authentication and doesn't require API keys

4. Verify your setup:

   For Cursor users:

   • Restart Cursor to load the new MCP configuration
   • Ask the AI: "Can you list all available MCP tools and test them?"
   • The AI should be able to access JIRA, Confluence, GitHub, Figma, and other configured services
   • For Figma: On first use, you'll be prompted to authenticate via OAuth flow in your browser

   For Augment users:

   bash Copy

   npx @augmentcode/auggie --mcp-config mcp.json "go over all my mcp tools and make sure they work as expected"

   For GitHub Copilot users:

   • Note: GitHub Copilot does not currently support MCP integration
   • MCP services (JIRA, Confluence, etc.) will not be available in Copilot

Available MCP Services Copy Section

The mcp.json file configures these services:

• github - GitHub integration (issues, PRs, repository operations)
• memory - Persistent context storage across sessions
• sequential-thinking - Enhanced reasoning for complex tasks
• context-7 - Advanced context management
• atlassian - JIRA (RI-XXX tickets) and Confluence integration (requires API tokens in .env.mcp)
• figma - Figma design files, frames, and layers (uses OAuth authentication - no API key needed)

Updating These Rules Copy Chapter

To update AI standards:

1. Edit SKILL.md files under .ai/skills/ (never edit symlinked files directly)
2. Update AGENTS.md if you change commands, testing instructions, or the always-on rules block
3. Changes propagate to Claude Code automatically via the .claude/ symlinks
4. Commit changes to version control

Remember: These rules exist to maintain code quality and consistency. Follow them, but also use good judgment.

Overview (`tests/e2e-playwright/README.md`) Copy Section

RedisInsight E2E Tests v2

Standalone Playwright E2E test suite for RedisInsight.

Documentation Copy Chapter

AI Commands Copy Section

Use these commands with Augment AI to generate and fix tests:

Example:

@e2e-generate http://localhost:8080/browser "add key"
@e2e-fix "Analytics > Slow Log"

Prerequisites Copy Chapter

Common Setup (All Projects) Copy Section

Start Redis Test Environment (RTE) using Docker Compose:

cd tests/e2e
docker-compose -f rte.docker-compose.yml up -d

For local runs, add these entries to /etc/hosts (one-off):

127.0.0.1 host.docker.internal
127.0.0.1 master-hostname-7-1 master-hostname-7-2 master-hostname-7-3

The clusters advertise these addresses to clients, and the API resolves them on your
host. Without them, cluster tests fail while creating a database with 500 /
errorCode 12500 ("Server closed the connection.").

Note: make sure they are appended as separate lines, and that the previous last
line of the file ends with a newline. The result should look like:

text Copy

127.0.0.1 host.docker.internal
127.0.0.1 master-hostname-7-1 master-hostname-7-2 master-hostname-7-3

not

text Copy

127.0.0.1 existing-entry127.0.0.1 host.docker.internal <--- these should be 2 lines

Verify with

grep -n "host.docker.internal\|master-hostname" /etc/hosts

Project-Specific Setup Copy Section

Note: Setup commands run from the repository root. Test commands run from tests/e2e-playwright/.

Installation Copy Chapter

cd tests/e2e-playwright
npm install
npx playwright install chromium

Configuration Copy Chapter

Copy example.env to .env and update values for your environment:

cp example.env .env

Environment variables:

• RI_CLIENT_URL - RedisInsight UI URL (default: http://localhost:8080)
• RI_API_URL - RedisInsight API URL (default: http://localhost:5540)
• OSS_STANDALONE_* - Standalone Redis connection details
• OSS_CLUSTER_* - Cluster Redis connection details
• OSS_SENTINEL_* - Sentinel Redis connection details

Running Tests Copy Chapter

Commands Copy Section

Chromium Browser Tests Copy Section

npm test                      # Run all tests
npm run test:chromium         # Run Chromium project only
npm run test:chromium:headed  # Watch tests run
npm run test:chromium:debug   # Pause and step through tests
npm run test:chromium:ui      # Interactive test runner

Electron Desktop Tests Copy Section

npm run test:electron         # Run all Electron tests
npm run test:electron:headed  # Watch the app
npm run test:electron:debug   # Debug with Inspector

Custom Executable Path

If you need to override the default path (e.g., for a custom build location):

ELECTRON_EXECUTABLE_PATH="/path/to/your/app" npm run test:electron

Default paths by platform:

Electron Test Considerations

• Single worker: Electron tests run with 1 worker (sequential execution)
• Longer timeouts: Electron tests have 120s timeout (vs 60s for browser)
• UI-based navigation: All navigation uses UI clicks (works for both browser and Electron)
• Same test files: Browser and Electron tests use the same test files

Navigation Methods

All navigation is UI-based for consistency across platforms.

BasePage provides fundamental navigation:

await this.gotoHome();              // Click Redis logo → databases list
await this.gotoDatabase(dbId);      // Click database → Browser page (default)

Each page has its own goto() method that handles navigation + waiting:

// Navigate to specific pages
await settingsPage.goto();           // Settings page
await browserPage.goto(dbId);        // Browser page for database
await workbenchPage.goto(dbId);      // Workbench page for database
await analyticsPage.goto(dbId);      // Analytics page for database
await pubSubPage.goto(dbId);         // Pub/Sub page for database

InstancePage provides tab switching within a connected database:

// Switch tabs (when already connected to a database)
await browserPage.navigationTabs.gotoBrowser();
await browserPage.navigationTabs.gotoWorkbench();
await browserPage.navigationTabs.gotoAnalyze();
await browserPage.navigationTabs.gotoPubSub();

Multi-Environment Support Copy Chapter

The framework supports multiple environments via the ENV variable:

# Local (default) - uses .env
npm test

# CI - uses .env.ci
ENV=ci npm test

# Staging - uses .env.staging
ENV=staging npm test

Create environment-specific .env.{name} files for different environments.

Folder Structure Copy Chapter

tests/e2e-playwright/
├── config/            # Environment configuration
├── fixtures/          # Test fixtures (page objects, API helpers)
├── helpers/           # Utility functions
├── pages/             # Page Object Models (component-based)
│   └── databases/
│       ├── DatabasesPage.ts
│       └── components/
│           ├── AddDatabaseDialog.ts
│           └── DatabaseList.ts
├── test-data/         # Test data factories
├── tests/             # Test files organized by project
│   ├── main/          # Main parallel tests (default)
│   │   ├── browser/
│   │   ├── workbench/
│   │   └── databases/
│   ├── auto-update/   # Auto-update tests (serial, special setup)
│   └── electron/      # Electron-specific tests
├── types/             # TypeScript type definitions
├── setup/             # Global setup/teardown per project
│   ├── browser.setup.ts
│   ├── browser.teardown.ts
│   ├── electron.setup.ts
│   └── electron.teardown.ts
└── playwright.config.ts

Page Object Structure Copy Section

Page objects are organized into component-based POMs for better maintainability:

BasePage (abstract)
  ├── DatabasesPage           # Databases list page
  ├── SettingsPage            # Settings page
  └── InstancePage (abstract) # Base for all database instance pages
        ├── instanceHeader    # Database name, stats, breadcrumb
        ├── navigationTabs    # Browse, Workbench, Analyze, Pub/Sub
        ├── bottomPanel       # CLI, Command Helper, Profiler
        └── BrowserPage       # Browser-specific (extends InstancePage)
              └── WorkbenchPage (future)
              └── AnalyzePage (future)
              └── PubSubPage (future)

• BasePage - Common navigation methods for all pages
• InstancePage - Base class for pages within a connected database (provides shared header, tabs, bottom panel)
• Component POMs (AddDatabaseDialog, KeyList) - Reusable UI components

// Access component POMs through the page
await databasesPage.addDatabaseDialog.fillForm(config);
await browserPage.keyList.selectKey(keyName);

// InstancePage provides common components
await browserPage.instanceHeader.getDatabaseName();
await browserPage.navigationTabs.gotoWorkbench();
await browserPage.bottomPanel.openCli();

Test Structure Copy Section

Tests are organized into projects (folders) based on execution requirements, then by feature:

tests/
├── parallel/               # Default — safe to run with multiple workers
│   ├── browser/
│   │   ├── add-key/
│   │   └── key-details/
│   ├── databases/
│   │   ├── add-database/
│   │   └── edit-database/
│   └── workbench/
└── serial/                 # Must run sequentially (shared DB state,
    │                       # dangerous commands, vector-index ops, etc.)
    ├── cli/
    ├── vector-search/
    └── workbench/

Playwright Projects Copy Section

The folder a test lives in determines its execution mode. Each browser platform has a parallel project and a serial project:

* Electron currently runs with a single worker because there is one app instance.

Execution order Copy Section

For each platform, the serial project depends on the parallel project (dependencies: ['-parallel'] in playwright.config.ts), so the order is always:

1. -parallel runs first (with up to N workers)
2. -serial runs after, one worker at a time

Why sequential instead of running them concurrently:

• Serial tests perform destructive operations on the shared RTE Redis (FLUSHDB, broad deleteAllIndexes, dangerous commands). Letting them run alongside parallel tests means a parallel test can observe a flushed/wiped database between its own steps.
• Electron also can't run the two projects concurrently because the desktop app binds its embedded API on a fixed port (5530), and two app instances would collide.
• Keeping chromium and electron on the same execution model keeps the mental model simple — folder location maps directly to position in the run.

If the serial suite grows large enough that this ordering becomes a CI bottleneck, the right next step is to give serial tests a dedicated Redis instance (or split into a separate CI job), not to revert the ordering.

Run specific projects:

# Full platform run (parallel + serial)
npx playwright test --project=chromium-parallel --project=chromium-serial
npx playwright test --project=electron-parallel --project=electron-serial

# Just parallel
npx playwright test --project=chromium-parallel

# Just serial — pass --no-deps, otherwise the parallel project runs first
# (it's listed in chromium-serial's dependencies). --no-deps also skips
# browser-setup, so make sure the app is already running locally.
npx playwright test --project=chromium-serial --no-deps

npx playwright test                           # All projects

When to put a test in tests/serial/:

• Tests share database state via beforeAll and would race other workers
• Tests run dangerous commands or mutate global app state
• Tests exercise flows that are inherently sequential (e.g. environment gating, single-resource index ops)

Writing Tests Copy Chapter

Tests are organized by feature area. Each test file should:

• Use descriptive test names
• Follow AAA pattern (Arrange, Act, Assert)
• Use Page Object Models for UI interactions
• Use faker for test data generation
• Use test data factories from test-data/
• Clean up created data in afterEach via API (faster and more reliable)

Example:

import { test, expect } from '../../../fixtures/base';
import { getStandaloneConfig } from '../../../test-data/databases';

test.describe('Add Database > Standalone', () => {
  test.afterEach(async ({ apiHelper }) => {
    // Clean up all test databases via API (fast)
    await apiHelper.deleteTestDatabases();
  });

  test('should add standalone database', async ({ databasesPage }) => {
    const config = getStandaloneConfig();

    await databasesPage.goto();
    await databasesPage.addDatabase(config);

    await expect(databasesPage.databaseList.getRow(config.name)).toBeVisible();
  });
});

API Helper Copy Chapter

Use the apiHelper fixture for test setup/teardown via API (faster than UI):

test('should work with pre-created database', async ({ databasesPage, apiHelper }) => {
  // Create database via API (fast)
  const db = await apiHelper.createDatabase(getStandaloneConfig());

  // Test UI behavior
  await databasesPage.goto();
  await expect(databasesPage.getDatabaseRow(db.name)).toBeVisible();

  // Cleanup via API
  await apiHelper.deleteDatabase(db.id);
});

Overview (`redisinsight/api/test/README.md`) Copy Section

Integration Tests

How to Run Copy Chapter

Prerequisites Copy Section

• First Time Running Tests?
  If you're running the tests for the first time, please review the Short Explanation and High-Level Overview.

• Running a Subset of Tests
  You can run a specific subset of tests by modifying the spec glob in /redisinsight/api/test/api/.mocharc.yml. This allows you to execute only the tests you need.

Steps to Run Tests Copy Section

1. Run the Desired Environment
   It's recommended to use Docker for this, as it provides better control over versioning and switching between environments.

2. Execute the Tests
   From the root directory of the repository, run the following command:

   bash Copy

   npm run test:api:integration

Example

Let’s walk through an example where you need to run tests related to string.

1. Modify the Test Subset
   Update /redisinsight/api/test/api/.mocharc.yml to include only the string tests:

   yaml Copy

   spec:
     - 'test/**/string/**/*.test.ts'

2. Run the Environment in Docker
   For this example, let’s assume you need to run the tests against the OSS-ST-6 environment. To do this:

   • Navigate to the environment directory:

     bash Copy

     cd /redisinsight/api/test/test-runs/oss-st-6

   • Start Docker:

     bash Copy

     docker-compose up

3. Run the Tests
   Finally, execute the tests from the root directory:

   bash Copy

   npm run test:api:integration

Short Explanation and High-Level Overview Copy Chapter

The integration tests follow a basic structure:

• Redis Environment: Tests are executed against various Redis environments such as Redis Community Edition (Redis OSS), Redis Cluster, Redis Stack, etc.
• Test Suites: A collection of test scenarios are designed to evaluate different Redis features.

Note: Keep in mind that specific Redis environments might require additional test suites. For example, Redis Stack includes RediSearch, which is not available in Redis OSS, meaning tests designed for RediSearch will fail if executed in a Redis OSS environment.

Project Structure Copy Section

Tests

The /redisinsight/api/test/api directory contains all the test scenarios for the integration tests.

Environments

The /redisinsight/api/test/test-runs directory houses the Redis Test Environments (RTEs). Some of these environments have more complex setups, such as TLS with authentication, and thus include all necessary components (e.g., keys, certificates).

Note: You may encounter some code related to GitHub Actions workflows, as these tests are also automatically run through CI/CD.

Overview (`redisinsight/ui/src/packages/clients-list/README.md`) Copy Section

Plugin for the “Client List” command

The plugin has been created using React, TypeScript, and Elastic UI.
Parcel is used to build the plugin.

Running locally Copy Chapter

The following commands will install dependencies and start the server to run the plugin locally:

npm install
npm start

These commands will install dependencies and start the server.

Note: Base styles are included to index.html
from RedisInsight repository.

From Redis Insight Repo:
This command will generate the vendor folder with styles and fonts of the core app. Add this folder
inside the folder for your plugin and include appropriate styles to the index.html file.

npm install
npm install --prefix redisinsight/api

npm run build:statics - for Linux or MacOs
npm run build:statics:win - for Windows

Build plugin Copy Chapter

The following commands will build plugins to be used in Redis Insight:

npm install
npm run build

Add the package.json file and the
dist folder to the folder with your plugin, which should be located in the plugins folder.

Overview (`redisinsight/ui/src/packages/geodata/README.md`) Copy Section

Geodata Workbench Plugin

Internal RedisInsight Workbench plugin for Redis GEO commands.

Visualizations Copy Chapter

• Geospatial map plots coordinate-bearing search results for GEOSEARCH, GEORADIUS, and GEORADIUSBYMEMBER.
• Geospatial heatmap renders the same coordinate-bearing search results as density.
• Geospatial details summarizes every Redis GEO command family, including write and store commands.

The map views require WITHCOORD in command output. The inspector can render scalar, integer, hash, position, search, and search-store responses without coordinates.

Geospatial map is the default visualization for coordinate search commands that include WITHCOORD. Geospatial details is the default for scalar, store, and non-coordinate GEO search commands, and remains selectable for coordinate search commands.

Tile Policy Copy Chapter

The plugin loads OSM tiles from the runtime default config; fallback renders unavailable state.

For an official upstream PR, maintainers may still require the default tile provider to be disabled or replaced by a Redis-approved tile backend.

Development Copy Chapter

npm install --prefix redisinsight/ui/src/packages/geodata
npm test --prefix redisinsight/ui/src/packages/geodata
npm run build --prefix redisinsight/ui/src/packages

Overview (`redisinsight/ui/src/packages/redisgraph/README.md`) Copy Section

RedisGraph Plugin for Redis Insight v2

The example has been created using React, TypeScript, and Elastic UI.
Parcel is used to build the plugin.

Running locally Copy Chapter

The following commands will install dependencies and start the server to run the plugin locally:

npm install
npm start

These commands will install dependencies and start the server.

Note: Base styles are included to index.html from the repository.

This command will generate the vendor folder with styles and fonts of the core app. Add this folder
inside the folder for your plugin and include appropriate styles to the index.html file.

npm run build:statics - for Linux or MacOs
npm run build:statics:win - for Windows

Build plugin Copy Chapter

The following commands will build plugins to be used in Redis Insight:

npm install
npm run build

Add the package.json file and the
dist folder to the folder with your plugin, which should be located in the plugins folder.

Overview (`redisinsight/ui/src/packages/redisinsight-plugin-sdk/README.md`) Copy Section

RedisInsight-plugin-sdk

The high-level API for communication between Redis Insight
plugin and Redis Insight application.

Usage Copy Chapter

npm install redisinsight-plugin-sdk
or
npm install redisinsight-plugin-sdk

Available methods Copy Chapter

setHeaderText(text) Copy Section

Sets any custom text to the header of the command result

Parameters:

• text {String}

Example:

import { setHeaderText } from 'redisinsight-plugin-sdk';
setHeaderText('Matched: 10');

executeRedisCommand(command) Copy Section

Executes a Redis command (currently, only read-only commands are supported).

Parameters:

• command {String} - command to execute

Returns:

• Promise<[{ response, status }]>

/**
 * @async
 * @param {String} command
 * @returns {Promise.<[{ response, status }]>}
 * @throws {Error}
 */

Example:

import { executeRedisCommand } from 'redisinsight-plugin-sdk';
try {
  const result = await executeRedisCommand('GET foo');
  const [{ response, status }] = result;
  if (status === 'success') {
    // Do smth
  }
} catch (e) {
  console.error(e);
}

getState() Copy Section

Returns saved state for the command visualization.

Throw an error if the state has not been saved.

Parameters:

• state {any} - any data to save

Returns:

• Promise<any>

/**
 * @async
 * @returns {Promise.<any>} state
 * @throws {Error}
 */

Example:

import { getState } from 'redisinsight-plugin-sdk';
try {
  const result = await getState();
} catch (e) {
  console.error(e);
}

setState(state) Copy Section

Save the state for the command visualization.

Returns:

• Promise<any>

/**
 * @async
 * @param {any} state
 * @returns {Promise.<any>} state
 * @throws {Error}
 */

Example:

import { setState } from 'redisinsight-plugin-sdk';
try {
  await setState({ a: 1, b: 2 });
} catch (e) {
  console.error(e);
}

formatRedisReply(response, command) Copy Section

Util function to parse Redis response

Returns string with parsed cli-like response

Returns:

• Promise<string>

/**
 * @async
 * @param {any} response
 * @param {String} command
 * @returns {Promise.<string>} data
 * @throws {Error}
 */

Example:

import { formatRedisReply } from 'redisinsight-plugin-sdk';

try {
  const parsedReply = await formatRedisReply(data[0].response, command);

  /*
    parsedReply:
    
    1) 1) "COUNT(a)"
    2) 1) 1) "0"
    3) 1) "Cached execution: 1"
       2) "Query internal execution time: 3.134125 milliseconds"
   */
} catch (e) {
  console.error(e);
}

Overview (`redisinsight/ui/src/packages/redistimeseries-app/README.md`) Copy Section

RedisTimeseries Plugin for Redis Insight

The example has been created using React, TypeScript, and Elastic UI.
Parcel is used to build the plugin.

Running locally Copy Chapter

The following commands will install dependencies and start the server to run the plugin locally:

npm install
npm start

These commands will install dependencies and start the server.

Note: Base styles are included to index.html from the repository.

This command will generate the vendor folder with styles and fonts of the core app. Add this folder
inside the folder for your plugin and include appropriate styles to the index.html file.

npm run build:statics - for Linux or MacOs
npm run build:statics:win - for Windows

Build plugin Copy Chapter

The following commands will build plugins to be used in Redis Insight:

npm install
npm run build

Add the package.json file and the
dist folder to the folder with your plugin, which should be located in the plugins folder.

Azure Docker Setup (`docs/azure-docker-setup.md`) Copy Section

Azure Authentication in Docker

This guide covers using Azure Entra ID authentication with RedisInsight when running in Docker.

Prerequisites: Your Azure tenant must have admin consent granted for RedisInsight. See Azure Setup Guide for initial setup.

Important: Localhost Access Required Copy Chapter

Azure Entra ID authentication in RedisInsight uses a public client application which only supports localhost redirect URIs. This means:

• ✅ Access via http://localhost:PORT - works
• ❌ Access via http://127.0.0.1:PORT - does not work
• ❌ Access via http://your-server-ip:PORT - does not work
• ❌ Access via custom domain - does not work

If you need to access RedisInsight from a remote machine, use SSH port forwarding:

ssh -L 5540:localhost:5540 user@remote-server
# Then access http://localhost:5540 on your local machine

Supported Ports Copy Chapter

Azure Entra ID authentication is supported on the following localhost ports:

When using a non-default port, set RI_EXTERNAL_URL to match:

docker run -p 8000:5540 -e RI_EXTERNAL_URL=http://localhost:8000 redis/redisinsight:latest

Note: Azure Entra ID authentication requires one of the supported localhost ports. Custom domains are not currently supported.

Quick Start Copy Chapter

Standard Docker (Port 5540) Copy Section

If you run RedisInsight on the default port, Azure authentication works out of the box:

docker run -d -p 5540:5540 redis/redisinsight:latest

Access at http://localhost:5540 and use "Sign in with Microsoft" to authenticate.

Custom Port Mapping Copy Section

When mapping to a different external port, set RI_EXTERNAL_URL so OAuth callbacks work correctly:

docker run -d \
  -p 8000:5540 \
  -e RI_EXTERNAL_URL=http://localhost:8000 \
  redis/redisinsight:latest

Access at http://localhost:8000.

Docker Compose Copy Section

version: '3'
services:
  redisinsight:
    image: redis/redisinsight:latest
    ports:
      - '8000:5540'
    environment:
      - RI_EXTERNAL_URL=http://localhost:8000
    volumes:
      - redisinsight-data:/data

volumes:
  redisinsight-data:

Reverse Proxy Setup Copy Chapter

When running behind a reverse proxy, RedisInsight will work normally for general usage. However, Azure Entra ID authentication requires accessing RedisInsight via one of the supported localhost ports.

Nginx Example Copy Section

server {
    listen 443 ssl;
    server_name redisinsight.example.com;

    location / {
        proxy_pass http://localhost:5540;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Note: For Azure Entra ID authentication, access RedisInsight directly via http://localhost:5540 instead of the reverse proxy URL.

Environment Variables Copy Chapter

Kubernetes / Helm Copy Chapter

When deploying to Kubernetes, use one of the supported ports and set RI_EXTERNAL_URL:

env:
  - name: RI_EXTERNAL_URL
    value: 'http://localhost:8000'

Azure Setup (`docs/azure-setup.md`) Copy Section

Azure Managed Redis Setup (formerly Azure Cache for Redis)

Setup Instructions Copy Chapter

To use the Azure integration, your Azure tenant administrator may need to grant admin consent for the RedisInsight application. This is a one-time setup per Azure tenant — once done, all users in your organization can use RedisInsight with Entra ID seamlessly.

Which tenant? The commands below must be run in the home tenant of every user who signs in through RedisInsight — this is not necessarily the tenant that owns the Azure Managed Redis resources. If your users belong to a different tenant than the one hosting the resources, see Multi-tenant scenarios.

Why is this needed? See Why This Setup is Required for details on the authentication flow.

Running in Docker? See Azure Docker Setup for configuration when using custom ports or reverse proxies.

App Registration Details Copy Section

• Application (Client) ID: 61f3d82d-2bf3-432a-ba1b-c056e4cf0fd0

Required Permissions Copy Section

The RedisInsight app requires the following API permissions:

Granting Admin Consent (Azure CLI) Copy Section

Run these commands in Azure Cloud Shell or your local terminal with Azure CLI installed:

# Step 1: Create the service principals in your tenant
# 61f3d82d-... = RedisInsight application
# acca5fbb-... = Azure Cache for Redis API (AzureRedisCacheAadApp)
az ad sp create --id 61f3d82d-2bf3-432a-ba1b-c056e4cf0fd0
az ad sp create --id acca5fbb-b7e4-4009-81f1-37e38fd66d78

# Step 2: Grant permissions
# Grant RedisInsight access to Azure Cache for Redis API
az ad app permission grant \
  --id 61f3d82d-2bf3-432a-ba1b-c056e4cf0fd0 \
  --api acca5fbb-b7e4-4009-81f1-37e38fd66d78 \
  --scope user_impersonation

# Grant RedisInsight access to Azure Resource Manager API
# 797f4846-... = Azure Resource Manager (for autodiscovery)
az ad app permission grant \
  --id 61f3d82d-2bf3-432a-ba1b-c056e4cf0fd0 \
  --api 797f4846-ba00-4fd7-ba43-dac1f8f63013 \
  --scope user_impersonation

# Step 3: Verify permissions were granted
az ad app permission list-grants \
  --id 61f3d82d-2bf3-432a-ba1b-c056e4cf0fd0 \
  --show-resource-name

You should see AzureRedisCacheAadApp and Windows Azure Service Management API (or Azure Resource Manager) in the output.

Multi-tenant scenarios Copy Chapter

By default, RedisInsight signs you in through the multi-tenant /common endpoint, which issues the access token against your home tenant. That works when your account and the Azure Managed Redis resources live in the same tenant. Two situations need extra attention:

• Your resources are in a different tenant than your account. The setup commands above (az ad sp create / az ad app permission grant) must exist in your home tenant — the tenant your user account belongs to — because that is where the token is issued. Running them only in the resource tenant is not enough and results in AADSTS650052.
• You are a guest / external user of the resource tenant. Sign in against that tenant explicitly (see Picking a tenant) so the token is issued there and its subscriptions become visible.

Personal Microsoft accounts. Azure Resource Manager and Azure Cache for Redis are organizational-only Azure APIs — a personal Microsoft account (e.g. @outlook.com) can't be issued tokens for them, so the default sign-in fails with "You can't sign in here with a personal account." (This isn't about the app registration, which does allow personal accounts; it's the resources that are org-only.) To use a personal account, invite it as a guest into the organizational tenant that owns the resources, then sign in against that tenant with the Tenant ID field (see below).

Cross-tenant access (resources and user in different tenants) Copy Section

Say the Azure Managed Redis lives in tenant A, but your user account's home is tenant B. To reach A's resources from RedisInsight:

1. Get invited to tenant A. An administrator of tenant A invites your account as a guest (Entra ID → External Identities), and you accept the invitation.
2. Get a role in tenant A. You need Reader on the subscription (or resource group) so autodiscovery can list it, plus a Redis data access policy (e.g. Data Owner) on the cache if you want to connect to the data, not just discover it.
3. Make sure tenant A is set up. The admin-consent commands must have been run in tenant A (the tenant the token will be issued for).
4. Sign in against tenant A. In RedisInsight, use the Tenant ID field (see below) to enter tenant A's ID. The token is issued by A, and A's subscriptions and databases appear.

Without the invitation and role (steps 1–2), sign-in may succeed but you'll see no subscriptions — see the troubleshooting note.

Picking a tenant Copy Section

When you click Azure Managed Redis, the sign-in dialog has an optional Tenant ID field. Enter a tenant GUID or domain (for example your-tenant.onmicrosoft.com) to authenticate against that specific tenant instead of your home tenant.

Use it when:

• Your home tenant differs from the tenant that owns the Azure Managed Redis resources, or
• You are a guest in the resource tenant and its subscriptions don't appear by default.

Leave the field blank to sign in against your home tenant (the default). The tenant you signed in with is shown on the subscriptions screen. To switch tenants, use the Switch account or tenant button there and enter a different tenant ID.

Troubleshooting Copy Chapter

Error: AADSTS650057 - Invalid resource Copy Section

If you see this error:

Invalid resource. The client has requested access to a resource which is not listed in the requested permissions in the client's application registration.

This means admin consent has not been granted for the RedisInsight application in your Azure tenant. Follow the "Granting Admin Consent (Azure CLI)" steps above.

Error: AADSTS65006 - No entitlements matching required permissions Copy Section

If you see this error:

Resource 'acca5fbb-...' had no entitlements matching required permissions configured on the required resource access for client '61f3d82d-...'.

This means the Azure Cache for Redis API permissions haven't been granted. Run these commands:

# Create the service principal for Azure Cache for Redis API
az ad sp create --id acca5fbb-b7e4-4009-81f1-37e38fd66d78

# Grant permission
az ad app permission grant \
  --id 61f3d82d-2bf3-432a-ba1b-c056e4cf0fd0 \
  --api acca5fbb-b7e4-4009-81f1-37e38fd66d78 \
  --scope user_impersonation

Error: AADSTS650052 - Lacks a service principal Copy Section

If you see this error:

The app is trying to access a service that your organization lacks a service principal for.

Run these commands to create the required service principals:

az ad sp create --id 61f3d82d-2bf3-432a-ba1b-c056e4cf0fd0
az ad sp create --id acca5fbb-b7e4-4009-81f1-37e38fd66d78

Then grant the permissions using the CLI commands above.

Multi-tenant note: This error most often means the service principals exist in the resource tenant but not in the tenant the token was issued for. The token is issued for your home tenant by default — so the commands must be run there. If your resources are in a different tenant, either run the setup in your home tenant, or sign in against the resource tenant using the Tenant ID field (see Picking a tenant).

Error: AADSTS50079 - Multi-factor authentication required Copy Section

If you see this error:

Due to a configuration change made by your administrator ... you must enroll in multi-factor authentication to access '797f4846-...'.

The tenant you're signing in against enforces MFA (via Security Defaults or a Conditional Access policy), and RedisInsight refreshes the management token silently, which can't complete an interactive MFA prompt. Enroll the account in MFA once (e.g. sign in to the Azure portal as that account in the target tenant and complete the prompt), then sign in to RedisInsight again. Once enrolled, silent token refresh carries the MFA claim and autodiscovery works.

Signed in successfully but no subscriptions appear Copy Section

Sign-in worked and there's no error, but the subscriptions list is empty. This means your account has no role in the tenant you signed in against. Azure only returns subscriptions your identity can access, so you need at least Reader on the subscription (or resource group). For a guest/cross-tenant sign-in, an administrator of that tenant must assign the role — see Cross-tenant access.

"You can't sign in here with a personal account" Copy Section

Azure Resource Manager and Azure Cache for Redis are organizational-only APIs, so a personal Microsoft account can't be issued tokens for them — even though RedisInsight's app registration itself allows personal accounts. Signing in via the default (blank) flow routes a personal account to its consumer tenant, where those resources don't exist, so Azure blocks it. To use a personal account, it must be a guest in the organizational tenant that owns the resources, and you must sign in using the Tenant ID field (enter that tenant) rather than the blank/default sign-in — the token is then issued in that tenant's context.

Why This Setup is Required Copy Chapter

How RedisInsight Authenticates Copy Section

RedisInsight uses PKCE (Proof Key for Code Exchange) OAuth 2.0 flow to authenticate with Azure Cache for Redis. This is a secure, public client flow recommended by Microsoft for desktop and web applications because:

• No client secrets — We don't store any secrets in the distributed application
• User-delegated access — Tokens are scoped to what you can access, not a service account
• Short-lived tokens — Access tokens expire and are refreshed automatically

Why Admin Consent is Needed Copy Section

Azure uses a multi-tenant security model. When you sign in through RedisInsight:

1. RedisInsight redirects you to Microsoft's login page
2. You authenticate with your Azure credentials
3. Azure checks if RedisInsight is allowed to request tokens on behalf of users in your tenant

Because RedisInsight is a third-party application, an Azure AD administrator must grant consent before users in your organization can authenticate through it. This gives organizations control over which applications can access their resources.

What Permissions Does RedisInsight Get? Copy Section

RedisInsight uses delegated permissions with user_impersonation scope. This means:

• RedisInsight can only access resources you already have access to
• We cannot access anything beyond your own permissions
• All access is auditable in your Azure AD logs

Plugins Development (`docs/plugins/development.md`) Copy Section

Plugin development

This document describes the guides to develop your own plugin for the Redis Insight Workbench.

How it works Copy Chapter

Plugin visualization in the Workbench is rendered using Iframe to encapsulate plugin scripts and styles, described in
the main plugin script and the stylesheet (if it has been specified in the package.json),
iframe includes basic styles as well.

Plugin structure Copy Chapter

Each plugin should have a unique name with all its files loaded to
a separate folder inside the default plugins folder.

Default plugins are located inside the application.

Files Copy Section

package.json should be located in the root folder of your plugins, all other files can be included into a subfolder.

• pluginName/package.json (required) - Manifest of the plugin
• pluginName/{anyName}.js (required) - Core script of the plugin
• pluginName/{anyName}.css (optional) - File with styles for the plugin visualizations
• pluginName/{anyFileOrFolder} (optional) - Specify any other file or folder inside the plugin folder
  to use by the core module script. For example: pluginName/images/image.png.

`package.json` structure Copy Chapter

This is the required manifest to use the plugin. package.json file should include
the following required fields:

Required fields in visualizations:
  
    ***id*** - visualization id
    ***name*** - visualization name to display in the Workbench
    ***activationMethod*** - name of the exported function to call when

this visualization is selected in the Workbench

***matchCommands*** - array of commands to use the visualization for. Supports regex string. 
      *Example: * ["CLIENT LIST", "FT.*"] |

You can specify the path to a css file in the styles field. If specified,
this file will be included inside the iframe plugin.

Simple example of the package.json file with required and optional fields:

{
  "author": {
    "name": "Redis Ltd.",
    "email": "[email protected]",
    "url": "https://redis.com/redis-enterprise/redis-insight"
  },
  "description": "Show client list as table",
  "styles": "./dist/styles.css",
  "main": "./dist/index.js",
  "name": "client-list",
  "version": "0.0.1",
  "scripts": {},
  "visualizations": [
    {
      "id": "clients-list",
      "name": "Table",
      "activationMethod": "renderClientsList",
      "matchCommands": ["CLIENT LIST"],
      "description": "Example of client list plugin",
      "default": true
    }
  ],
  "devDependencies": {},
  "dependencies": {}
}

Core script of the plugin Copy Chapter

This is the required script with defined visualization methods.
The core script contains function and its export (functions - for multiple visualizations),
which is run after the relevant visualization is selected in the Workbench.

The following function receives props of the executed commands:

interface Props {
  command: string; // executed command
  data: Result[]; // array of results (one item for Standalone)
}

interface Result {
  response: any; // response of the executed command
  status: 'success' | 'fail'; // response status of the executed command
}

const renderVisualization = (props: Props) => {
  // Do your magic
};

export default { renderVisualization };

Each plugin iframe has basic styles of Redis Insight application, including fonts and color schemes.

It is recommended to use the React & Elastic UI library for
consistency with plugin visualisations and the entire application.

Find the example of the plugin here.

• Client List Plugin README
• Client List Plugin dir

Available parameters Copy Section

Additional information provided to the plugin iframe is included in the window.state
inside of the plugin script.

const { config, modules } = window.state;
const { baseUrl, appVersion } = config;

// modules - the list of modules of the current database
// baseUrl - url for your plugin folder - can be used to include your assets
// appVersion - version of the Redis Insight application

Plugin rendering Copy Section

To render the plugin visualization, the iframe with basic html is generated which is
then populated with relevant scripts and styles. To render the html data, use existing
DOM Element #app or create your own DOM Elements.
Rendered iframe also includes theme_DARK or theme_LIGHT className on body to indicate the application theme used.

Javascript Example:

const renderVisualization = (props) => {
  const { command, data = [] } = props;
  const [{ result, status }] = data;
  document.getElementById('app').innerHTML = `
        <h3>Executed command:<h3>
        <p>${command}</p>
        <h4>Result of the command</h4>
        <p>${result}</p>
        <h4>Status of the command</h4>
        <p>${status}</p>
      `;
};

export default { renderVisualization };

React Example:

import { render } from 'react-dom';
import App from './App';

const renderVisualization = (props) => {
  const { command, data = [] } = props;
  const [{ result, status }] = data;
  render(
    <App command={command} response={result} status={status} />,
    document.getElementById('app'),
  );
};

// This is a required action - export the main function for execution of the visualization
export default { renderVisualization };

Plugin communication Copy Chapter

Use the redisinsight-plugin-sdk, which is a third party library,
to communicate with the main app.

Find the list and
description of methods called in the
README.md.

Plugins Installation (`docs/plugins/installation.md`) Copy Section

Plugin installation & Usage

This document describes the guides to add plugins for the Workbench to Redis Insight.

Installation guide Copy Chapter

Note: While adding new plugins for Workbench, use files only from trusted
authors to avoid automatic execution of malicious code.

1. Download the plugin for the Workbench.
2. Open the plugins folder with the following path
   • For MacOs: /.redis-insight/plugins
   • For Windows: C:/Users/{Username}/.redis-insight/plugins
   • For Linux: /.redis-insight/plugins
3. Add the folder with plugin to the plugins folder

To see the uploaded plugin visualizations in the command results, reload the Workbench
page and run Redis command relevant for this visualization.

Usage Copy Chapter

The plugin may contain different visualizations for any Redis commands.
Below you can find a guide to see command results in the uploaded plugin visualization:

1. Open Redis Insight
2. Open a database added
3. Open the Workbench
4. Run the Redis command relevant for the plugin visualization
5. Select the plugin visualization to display results in (if this visualization has not been set by default)

Plugins Introduction (`docs/plugins/introduction.md`) Copy Section

Introduction to plugins for the Workbench

Introduction Copy Chapter

Redis can hold a range of different data types. Visualizing these in a
format that’s convenient to you for validation and debugging is paramount.
You can now easily extend the core functionality of Redis Insight independently by
building your own custom visualization plugin.

Data visualization provided by the plugin is rendered within the
Workbench results area and is based on the executed command, ie. a certain
Redis command can generate its own custom data visualization.

We have included the following plugin package example for your reference: running the CLIENT LIST command presents the output in a tabular format for easier reading.

Wiki Copy Chapter

• Installation and Usage
• Plugin Development

--- METRICS ---

• Files Extracted: 14
• Estimated Token Budget: ~15133 tokens
• Canonical Reference: https://codewiki.google/github.com/redis/RedisInsight