Set up Redis Iris with the SDK and CLI

Install the redis-iris SDK and iris CLI, connect them to Redis Cloud or a self-managed deployment.

The redis-iris package is the Python software development kit (SDK) for every Redis Iris service, plus the iris command-line interface (CLI), which creates services, mints keys, and checks connections. Your agent reads only IRIS_* environment variables, so the same code runs on Redis Cloud and on a self-managed deployment.

Start with a service's quickstart: Agent Memory, Agent Playbooks, Context Gateway, Intent Router, or Lens. This page covers the setup they share.

redis-iris covers Python and the CLI. For JavaScript and TypeScript, each service has its own @redis-iris/* npm package, shown in its quickstart.

Install the SDK and CLI

Both require Python 3.11 or later.

python -m pip install redis-iris   # the SDK, in your project's virtual environment
pipx install redis-iris            # the iris CLI, in its own environment
iris --version

Agent setup

Install the Redis agent skills for your coding agent:

npx skills add redis/agent-skills

Then ask your agent, for example: "Add Redis Agent Memory to this app."

Learn the command shape

Every command has the same shape. Shared options go before the service name:

iris [shared options] <service> <noun> <verb> [arguments] [options]

For example, this command syncs a folder of FAQs to a playbook:

iris --json --profile suite agent-playbooks faqs sync ./faqs --publish changed

--json prints one JSON value, --no-input never prompts, and --profile selects a configuration profile. Run iris <service> <noun> <verb> --help for each command's options.

iris --help lists every service group, and --help at any level lists its commands, so the CLI is its own reference.

Set up on Redis Cloud

On Redis Cloud, the Redis Cloud console creates services and keys, and the CLI checks the connection. These steps use Agent Playbooks. The other Redis Iris services follow the same steps with their own console pages and IRIS_<SERVICE>_* variables. To see how the pieces fit together first, read Redis Iris concepts.

1. Create a playbook and wait until it is Ready.

2. Select Connect on the playbook's page. Copy the Endpoint and Playbook ID.

3. Create an API key with read for runtime retrieval. The authoring quickstart needs a separate key with write and publish. The console shows each key only once.

4. Save the values in a .env file:

   IRIS_AGENT_PLAYBOOKS_URL=<agent-endpoint>
   IRIS_AGENT_PLAYBOOKS_PLAYBOOK_ID=<playbook-id>
   IRIS_AGENT_PLAYBOOKS_API_KEY=<agent-api-key>
   

5. Optional, but recommended: create iris.toml with a cloud profile, and add IRIS_PROFILE=cloud and IRIS_CONFIG=./iris.toml to .env. One iris.toml holds the URLs for every Redis Iris service you use, so the CLI and SDK manage them together, and switching deployments means switching one profile.

   [profiles.cloud]
   kind = "cloud"
   
   [profiles.cloud.agent_playbooks]
   url = "<agent-endpoint>"
   

6. Load the values and check the connection with the agent key:

   set -a; source .env; set +a
   iris agent-playbooks health
   

   A working playbook reports status: READY.

Set up on a self-managed deployment

On a self-managed deployment, the CLI creates services and keys with your operator tokens. Each token is the deployment's static admin token or an access token from your identity provider.

The Playbooks commands in this section require an already deployed Playbooks control plane, data plane, and Identity Service. The CLI does not install a deployment.

The services deploy on Kubernetes from the shared Redis Helm repository, https://helm.redis.io/ai. Each has its own self-managed guide:

• Self-managed Agent Memory
• Self-managed Agent Playbooks
• Self-managed Context Gateway
• Self-managed Intent Router
• Self-managed Lens (beta)
• Identity Service, which every self-managed service uses for agent keys

1. Create iris.toml with a profile for your deployment. It holds URLs only:

   [profiles.suite]
   kind = "self-managed"
   
   [profiles.suite.agent_playbooks]
   service_url = "<playbook-service-url>"
   url = "<playbook-data-plane-url>"
   identity_url = "<identity-service-url>"
   

2. Put the operator tokens in a .env.admin file. Keep them out of your agent's .env:

   IRIS_CONFIG=./iris.toml
   IRIS_PROFILE=suite
   IRIS_AGENT_PLAYBOOKS_SERVICE_TOKEN=<service-token>
   IRIS_AGENT_PLAYBOOKS_IDENTITY_TOKEN=<identity-token>
   

3. Load the tokens and do a dry run. It sends nothing, and missing: nothing means the real run has every credential and URL it needs:

   set -a; source .env.admin; set +a
   iris agent-playbooks service create --name support-playbook --dry-run
   

4. Create the playbook. The CLI mints its agent key and writes the URL, ID, and key to .env. It never prints the key:

   iris agent-playbooks service create --name support-playbook --write-env .env
   

5. Check every hop, from the service to a read with the agent key:

   set -a; source .env; set +a
   iris agent-playbooks service check "$IRIS_AGENT_PLAYBOOKS_PLAYBOOK_ID" --env-file .env
   

Agent Memory, Context Gateway, and Intent Router follow the same steps with their own service create options.

Configure profiles and credentials

The CLI takes each setting from the first of these that sets it: a command option, an environment variable, the selected profile in iris.toml, the file's shared tables, then a built-in default.

iris.toml never holds secrets. A token or API key in it stops the CLI with exit code 2. Tokens and keys come only from environment variables or the files the CLI writes.

More information

• redis-iris on PyPI
• Redis Iris concepts