{
  "schema_version": 2,
  "id": "develop/ai/context-engine/sdk-and-cli",
  "title": "Set up Redis Iris with the SDK and CLI",
  "url": "https://redis.io/docs/latest/develop/ai/context-engine/sdk-and-cli/",
  "summary": "Install the redis-iris SDK and iris CLI, connect them to Redis Cloud or a self-managed deployment.",
  "tags": [
    "docs",
    "develop",
    "ai"
  ],
  "last_updated": "2026-11-03T16:54:25-08:00",
  "page_type": "content",
  "content_hash": "5f7a0f56d01e89721bec3b48909706aba8637528e7932d28945934a440f0d0f2",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "The [`redis-iris`](https://pypi.org/project/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.\n\nStart with a service's quickstart: [Agent Memory](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/quickstart), [Agent Playbooks](https://redis.io/docs/latest/develop/ai/context-engine/agent-playbooks/quickstart), [Context Gateway](https://redis.io/docs/latest/develop/ai/context-engine/context-gateway/quickstart), [Intent Router](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/quickstart), or [Lens](https://redis.io/docs/latest/develop/ai/context-engine/lens/quickstart). This page covers the setup they share.\n\n`redis-iris` covers Python and the CLI. For JavaScript and TypeScript, each service has its own `@redis-iris/*` npm package, shown in its quickstart."
    },
    {
      "id": "install-the-sdk-and-cli",
      "title": "Install the SDK and CLI",
      "role": "setup",
      "text": "Both require Python 3.11 or later.\n\n[code example]"
    },
    {
      "id": "agent-setup",
      "title": "Agent setup",
      "role": "content",
      "text": "Install the [Redis agent skills](https://github.com/redis/agent-skills) for your coding agent:\n\n[code example]\n\nThen ask your agent, for example: \"Add Redis Agent Memory to this app.\""
    },
    {
      "id": "learn-the-command-shape",
      "title": "Learn the command shape",
      "role": "content",
      "text": "Every command has the same shape. Shared options go before the service name:\n\n[code example]\n\nFor example, this command syncs a folder of FAQs to a playbook:\n\n[code example]\n\n| Part | Role | What it does |\n|---|---|---|\n| `--json --profile suite` | Shared options | Print the result as one JSON value, and use the `suite` profile from `iris.toml`. |\n| `agent-playbooks` | Service | Target Agent Playbooks. |\n| `faqs sync` | Noun and verb | Make the playbook's FAQs match the files. |\n| `./faqs` | Argument | The folder of FAQ files to sync. |\n| `--publish changed` | Option | Publish the new version of each FAQ that changed. Other FAQs keep their published version. |\n\n| Service group | What it manages |\n|---|---|\n| `agent-memory` | Agent Memory stores, memories, and sessions |\n| `agent-playbooks` | Agent Playbooks, FAQs, skills, proposals, and extraction from Agent Memory |\n| `context-gateway` | Context Gateways, their upstreams and tool policies, and tool calls |\n| `intent-router` | Intent Routers, intents, examples, and matching |\n| `identity` | Agent keys for every service: list, rotate, and revoke |\n\n`--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.\n\n`iris --help` lists every service group, and `--help` at any level lists its commands, so the CLI is its own reference."
    },
    {
      "id": "set-up-on-redis-cloud",
      "title": "Set up on Redis Cloud",
      "role": "content",
      "text": "On Redis Cloud, the [Redis Cloud console](https://cloud.redis.io/) 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](https://redis.io/docs/latest/develop/ai/context-engine/concepts).\n\n1. [Create a playbook](https://redis.io/docs/latest/operate/iris/agent-playbook/create-playbook) and wait until it is **Ready**.\n1. Select **Connect** on the playbook's page. Copy the **Endpoint** and **Playbook ID**.\n1. [Create an API key](https://redis.io/docs/latest/operate/iris/agent-playbook/create-playbook#give-an-agent-access) with `read` for runtime retrieval. The authoring quickstart needs a separate key with `write` and `publish`. The console shows each key only once.\n1. Save the values in a `.env` file:\n\n    [code example]\n\n1. 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.\n    <!-- TODO: link the Redis Cloud project setup example once it is public. -->\n\n    [code example]\n\n1. Load the values and check the connection with the agent key:\n\n    [code example]\n\n    A working playbook reports `status: READY`."
    },
    {
      "id": "set-up-on-a-self-managed-deployment",
      "title": "Set up on a self-managed deployment",
      "role": "content",
      "text": "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.\n\nThe Playbooks commands in this section require an already deployed Playbooks control plane, data plane, and Identity Service. The CLI does not install a deployment.\n\nThe services deploy on Kubernetes from the shared Redis Helm repository, [https://helm.redis.io/ai](https://helm.redis.io/ai). Each has its own self-managed guide:\n\n- [Self-managed Agent Memory](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed)\n- [Self-managed Agent Playbooks](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed)\n- [Self-managed Context Gateway](https://redis.io/docs/latest/operate/iris/context-gateway/self-managed)\n- [Self-managed Intent Router](https://redis.io/docs/latest/operate/iris/intent-router/self-managed)\n- [Self-managed Lens](https://redis.io/docs/latest/operate/iris/lens/self-managed) (beta)\n- [Identity Service](https://redis.io/docs/latest/operate/iris/identity-service), which every self-managed service uses for agent keys\n\n\n\n1. Create `iris.toml` with a profile for your deployment. It holds URLs only:\n\n    [code example]\n\n1. Put the operator tokens in a `.env.admin` file. Keep them out of your agent's `.env`:\n\n    [code example]\n\n1. 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:\n\n    [code example]\n\n1. Create the playbook. The CLI mints its agent key and writes the URL, ID, and key to `.env`. It never prints the key:\n\n    [code example]\n\n1. Check every hop, from the service to a read with the agent key:\n\n    [code example]\n\nAgent Memory, Context Gateway, and Intent Router follow the same steps with their own `service create` options."
    },
    {
      "id": "configure-profiles-and-credentials",
      "title": "Configure profiles and credentials",
      "role": "configuration",
      "text": "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.\n\n| Key in a profile | Meaning |\n|---|---|\n| `kind` | `self-managed` (the default) or `cloud` |\n| `service_url` | The service's control plane, which the CLI calls |\n| `url` | The data plane your agent calls. The CLI writes it into `.env` |\n| `identity_url` | The Identity Service that mints this service's keys |\n| `database_id` | Agent Memory only: the database `service create` puts a store in when neither `--database` nor `service.yaml` names one. Default `1` |\n| `[profiles.<name>.identity]` `url`, `tenant` | An Identity Service shared by every service, and its tenant |\n\n`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."
    },
    {
      "id": "more-information",
      "title": "More information",
      "role": "content",
      "text": "- [redis-iris on PyPI](https://pypi.org/project/redis-iris/)\n- [Redis Iris concepts](https://redis.io/docs/latest/develop/ai/context-engine/concepts)"
    }
  ],
  "examples": [
    {
      "id": "install-the-sdk-and-cli-ex0",
      "language": "bash",
      "code": "python -m pip install redis-iris   # the SDK, in your project's virtual environment\npipx install redis-iris            # the iris CLI, in its own environment\niris --version",
      "section_id": "install-the-sdk-and-cli"
    },
    {
      "id": "agent-setup-ex0",
      "language": "bash",
      "code": "npx skills add redis/agent-skills",
      "section_id": "agent-setup"
    },
    {
      "id": "learn-the-command-shape-ex0",
      "language": "bash",
      "code": "iris [shared options] <service> <noun> <verb> [arguments] [options]",
      "section_id": "learn-the-command-shape"
    },
    {
      "id": "learn-the-command-shape-ex1",
      "language": "bash",
      "code": "iris --json --profile suite agent-playbooks faqs sync ./faqs --publish changed",
      "section_id": "learn-the-command-shape"
    },
    {
      "id": "set-up-on-redis-cloud-ex0",
      "language": "bash",
      "code": "IRIS_AGENT_PLAYBOOKS_URL=<agent-endpoint>\n    IRIS_AGENT_PLAYBOOKS_PLAYBOOK_ID=<playbook-id>\n    IRIS_AGENT_PLAYBOOKS_API_KEY=<agent-api-key>",
      "section_id": "set-up-on-redis-cloud"
    },
    {
      "id": "set-up-on-redis-cloud-ex1",
      "language": "toml",
      "code": "[profiles.cloud]\n    kind = \"cloud\"\n\n    [profiles.cloud.agent_playbooks]\n    url = \"<agent-endpoint>\"",
      "section_id": "set-up-on-redis-cloud"
    },
    {
      "id": "set-up-on-redis-cloud-ex2",
      "language": "bash",
      "code": "set -a; source .env; set +a\n    iris agent-playbooks health",
      "section_id": "set-up-on-redis-cloud"
    },
    {
      "id": "set-up-on-a-self-managed-deployment-ex0",
      "language": "toml",
      "code": "[profiles.suite]\n    kind = \"self-managed\"\n\n    [profiles.suite.agent_playbooks]\n    service_url = \"<playbook-service-url>\"\n    url = \"<playbook-data-plane-url>\"\n    identity_url = \"<identity-service-url>\"",
      "section_id": "set-up-on-a-self-managed-deployment"
    },
    {
      "id": "set-up-on-a-self-managed-deployment-ex1",
      "language": "bash",
      "code": "IRIS_CONFIG=./iris.toml\n    IRIS_PROFILE=suite\n    IRIS_AGENT_PLAYBOOKS_SERVICE_TOKEN=<service-token>\n    IRIS_AGENT_PLAYBOOKS_IDENTITY_TOKEN=<identity-token>",
      "section_id": "set-up-on-a-self-managed-deployment"
    },
    {
      "id": "set-up-on-a-self-managed-deployment-ex2",
      "language": "bash",
      "code": "set -a; source .env.admin; set +a\n    iris agent-playbooks service create --name support-playbook --dry-run",
      "section_id": "set-up-on-a-self-managed-deployment"
    },
    {
      "id": "set-up-on-a-self-managed-deployment-ex3",
      "language": "bash",
      "code": "iris agent-playbooks service create --name support-playbook --write-env .env",
      "section_id": "set-up-on-a-self-managed-deployment"
    },
    {
      "id": "set-up-on-a-self-managed-deployment-ex4",
      "language": "bash",
      "code": "set -a; source .env; set +a\n    iris agent-playbooks service check \"$IRIS_AGENT_PLAYBOOKS_PLAYBOOK_ID\" --env-file .env",
      "section_id": "set-up-on-a-self-managed-deployment"
    }
  ]
}