{ "schema_version": 2, "id": "develop/ai/redisvl/api/cli", "title": "Command Line Interface", "url": "https://redis.io/docs/latest/develop/ai/redisvl/api/cli/", "summary": "", "aliases": [ "/integrate/redisvl/api/cli" ], "tags": [], "last_updated": "2026-10-05T16:11:44+01:00", "page_type": "content", "content_hash": "5443234e8f9c88b8ffe555d6e7d3982b8d9baeb9f9453339b3cba29338be0865", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "RedisVL provides a command line interface (CLI) called `rvl` for managing vector search indices. The CLI enables you to create, inspect, and delete indices directly from your terminal without writing Python code." }, { "id": "installation", "title": "Installation", "role": "setup", "text": "The `rvl` command is included when you install RedisVL.\n\n[code example]\n\nVerify the installation by running:\n\n[code example]" }, { "id": "connection-configuration", "title": "Connection Configuration", "role": "content", "text": "The CLI connects to Redis using the following resolution order:\n\n1. The `REDIS_URL` environment variable, if set\n2. Explicit connection flags (`--host`, `--port`, `--url`)\n3. Default values (`localhost:6379`)\n\n**Connection Flags**\n\nAll commands that interact with Redis accept these optional flags:\n\n| Flag | Type | Description | Default |\n|--------------------|---------|-------------------------------------------------|-------------|\n| `-u`, `--url` | string | Full Redis URL (e.g., `redis://localhost:6379`) | None |\n| `--host` | string | Redis server hostname | `localhost` |\n| `-p`, `--port` | integer | Redis server port | `6379` |\n| `--user` | string | Redis username for authentication | `default` |\n| `-a`, `--password` | string | Redis password for authentication | Empty |\n| `--ssl` | flag | Enable SSL/TLS encryption | Disabled |\n\n**Examples**\n\nConnect using environment variable:\n\n[code example]\n\nConnect with explicit host and port:\n\n[code example]\n\nConnect with authentication and SSL:\n\n[code example]" }, { "id": "getting-help", "title": "Getting Help", "role": "content", "text": "All commands support the `-h` and `--help` flags to display usage information.\n\n| Flag | Description |\n|----------------|-------------------------------------------|\n| `-h`, `--help` | Display usage information for the command |\n\n**Examples**\n\n[code example]\n\nRunning `rvl` without any arguments also displays the top-level help message." }, { "id": "commands", "title": "Commands", "role": "syntax", "text": "" }, { "id": "rvl-version", "title": "`rvl version`", "role": "content", "text": "Display the installed RedisVL version.\n\n**Syntax**\n\n[code example]\n\n**Options**\n\n| Option | Description |\n|-----------------|-------------------------------------------------------------|\n| `-s`, `--short` | Print only the version number without additional formatting |\n\n**Examples**\n\n[code example]" }, { "id": "rvl-index", "title": "`rvl index`", "role": "content", "text": "Manage vector search indices. This command group provides subcommands for creating, inspecting, listing, and removing indices.\n\n**Syntax**\n\n[code example]\n\n**Subcommands**\n\n| Subcommand | Description |\n|--------------|------------------------------------------------------|\n| `create` | Create a new index from a YAML schema file |\n| `info` | Display detailed information about an index |\n| `listall` | List all existing indices in the Redis instance |\n| `delete` | Remove an index while preserving the underlying data |\n| `destroy` | Remove an index and delete all associated data |\n\n#### `rvl index create`\n\nCreate a new vector search index from a YAML schema definition.\n\n**Syntax**\n\n[code example]\n\n**Required Options**\n\n| Option | Description |\n|------------------|-----------------------------------------------------------|\n| `-s`, `--schema` | Path to the YAML schema file defining the index structure |\n\n**Example**\n\n[code example]\n\n**Schema File Format**\n\nThe schema file must be valid YAML with the following structure:\n\n[code example]\n\n#### `rvl index info`\n\nDisplay detailed information about an existing index, including field definitions and index options.\n\n**Syntax**\n\n[code example]\n\n**Options**\n\n| Option | Description |\n|------------------|----------------------------------------------------------------|\n| `-i`, `--index` | Name of the index to inspect |\n| `-s`, `--schema` | Path to the schema file (alternative to specifying index name) |\n\n**Example**\n\n[code example]\n\n**Output**\n\nThe command displays two tables:\n\n1. **Index Information** containing the index name, storage type, key prefixes, index options, and indexing status\n2. **Index Fields** listing each field with its name, attribute, type, and any additional field options\n\n#### `rvl index listall`\n\nList all vector search indices in the connected Redis instance.\n\n**Syntax**\n\n[code example]\n\n**Example**\n\n[code example]\n\n**Output**\n\nReturns a numbered list of all index names:\n\n[code example]\n\n> [!NOTE]\n> `listall` uses `FT._LIST`, which Redis tags `@admin` as well as `@search`.\n> An ACL that grants search access and then subtracts `@admin`, such as\n> `+@search -@admin`, denies this command with a permission error even though the\n> rest of the CLI works. The migration commands that discover indexes for you are\n> denied by the same ACL: `rvl migrate helper`, `rvl migrate wizard` when no\n> `-i/--index` is given, and `rvl migrate batch-plan --pattern`. See\n> [Install RedisVL](https://redis.io/docs/latest/../user_guide/installation).\n\n#### `rvl index delete`\n\nRemove an index from Redis while preserving the underlying data. Use this when you want to rebuild an index with a different schema without losing your data.\n\n**Syntax**\n\n[code example]\n\n**Options**\n\n| Option | Description |\n|------------------|----------------------------------------------------------------|\n| `-i`, `--index` | Name of the index to delete |\n| `-s`, `--schema` | Path to the schema file (alternative to specifying index name) |\n\n**Example**\n\n[code example]\n\n#### `rvl index destroy`\n\nRemove an index and permanently delete all associated data from Redis. This operation cannot be undone.\n\n**Syntax**\n\n[code example]\n\n**Options**\n\n| Option | Description |\n|------------------|----------------------------------------------------------------|\n| `-i`, `--index` | Name of the index to destroy |\n| `-s`, `--schema` | Path to the schema file (alternative to specifying index name) |\n\n**Example**\n\n[code example]\n\n> [!WARNING]\n> This command permanently deletes both the index and all documents stored with the index prefix. Ensure you have backups before running this command." }, { "id": "rvl-stats", "title": "`rvl stats`", "role": "content", "text": "Display statistics about an existing index, including document counts, memory usage, and indexing performance metrics.\n\n**Syntax**\n\n[code example]\n\n**Options**\n\n| Option | Description |\n|------------------|----------------------------------------------------------------|\n| `-i`, `--index` | Name of the index to query |\n| `-s`, `--schema` | Path to the schema file (alternative to specifying index name) |\n\n**Example**\n\n[code example]\n\n**Statistics Reference**\n\nThe command returns the following metrics:\n\n| Metric | Description |\n|-------------------------------|--------------------------------------------|\n| `num_docs` | Total number of indexed documents |\n| `num_terms` | Number of distinct terms in text fields |\n| `max_doc_id` | Highest internal document ID |\n| `num_records` | Total number of index records |\n| `percent_indexed` | Percentage of documents fully indexed |\n| `hash_indexing_failures` | Number of documents that failed to index |\n| `number_of_uses` | Number of times the index has been queried |\n| `bytes_per_record_avg` | Average bytes per index record |\n| `doc_table_size_mb` | Document table size in megabytes |\n| `inverted_sz_mb` | Inverted index size in megabytes |\n| `key_table_size_mb` | Key table size in megabytes |\n| `offset_bits_per_record_avg` | Average offset bits per record |\n| `offset_vectors_sz_mb` | Offset vectors size in megabytes |\n| `offsets_per_term_avg` | Average offsets per term |\n| `records_per_doc_avg` | Average records per document |\n| `sortable_values_size_mb` | Sortable values size in megabytes |\n| `total_indexing_time` | Total time spent indexing in milliseconds |\n| `total_inverted_index_blocks` | Number of inverted index blocks |\n| `vector_index_sz_mb` | Vector index size in megabytes |" }, { "id": "rvl-migrate", "title": "`rvl migrate`", "role": "content", "text": "> [!WARNING]\n> The index migrator is an **experimental** feature. APIs, CLI commands, and on-disk formats (plans, checkpoints, backups) may change in future releases. Review migration plans carefully before applying to production indexes.\n\nManage document-preserving index migrations. This command group provides subcommands for planning, executing, and validating schema migrations that preserve existing data.\n\n**Syntax**\n\n[code example]\n\n**Subcommands**\n\n| Subcommand | Description |\n|----------------|----------------------------------------------------------------|\n| `helper` | Show migration guidance and supported capabilities |\n| `wizard` | Interactively build a migration plan and schema patch |\n| `plan` | Generate a migration plan from a schema patch or target schema |\n| `apply` | Execute a reviewed drop/recreate migration plan |\n| `estimate` | Estimate disk space required for a migration (dry-run) |\n| `rollback` | Restore original vectors from a backup directory |\n| `validate` | Validate a completed migration against the live index |\n| `batch-plan` | Generate a batch migration plan for multiple indexes |\n| `batch-apply` | Execute a batch migration plan with state tracking |\n| `batch-resume` | Resume an interrupted batch migration |\n| `batch-status` | Show status of an in-progress or completed batch migration |\n\n#### `rvl migrate plan`\n\nGenerate a migration plan for a document-preserving drop/recreate migration.\n\n**Syntax**\n\n[code example]\n\n**Required Options**\n\n| Option | Description |\n|-------------------|-----------------------------------------------------------------------------------|\n| `--index`, `-i` | Name of the source index to migrate |\n| `--schema-patch` | Path to a YAML schema patch file (mutually exclusive with `--target-schema`) |\n| `--target-schema` | Path to a full target schema YAML file (mutually exclusive with `--schema-patch`) |\n\n**Optional Options**\n\n| Option | Description |\n|--------------|--------------------------------------------------------------------------|\n| `--plan-out` | Output path for the migration plan YAML (default: `migration_plan.yaml`) |\n\n**Example**\n\n[code example]\n\n#### `rvl migrate apply`\n\nExecute a reviewed drop/recreate migration plan. Use `--async` for large migrations involving vector quantization.\n\n> [!WARNING]\n> Hash vector quantization is unsupported when the same Redis keys are also\n> indexed by another live RediSearch index that expects the old vector\n> datatype. Quantization rewrites vector bytes in the document key itself, so\n> other indexes covering the same key may drop the document or fail to index\n> it. Use an application-level migration with new keys or fields when\n> documents are shared across indexes.\n\n**Syntax**\n\n[code example]\n\n**Required Options**\n\n| Option | Description |\n|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `--plan` | Path to the migration plan YAML file |\n| `--backup-dir` | Required migration backup directory. Vector backup files are written when hash vector bytes are mutated; index-only and JSON migrations validate and record the directory without writing vector backup files. |\n\n**Optional Options**\n\n| Option | Description |\n|----------------------|------------------------------------------------------------------------|\n| `--async` | Run migration asynchronously (recommended for large quantization jobs) |\n| `--batch-size` | Keys per pipeline batch (default 500) |\n| `--workers` | Number of parallel workers for quantization (default 1). |\n| `--query-check-file` | Path to a YAML file with post-migration query checks |\n\n**Example**\n\n[code example]\n\n#### `rvl migrate wizard`\n\nInteractively build a schema patch and migration plan through a guided wizard.\n\n**Syntax**\n\n[code example]\n\n**Example**\n\n[code example]\n\n#### `rvl migrate rollback`\n\nRestore original vector bytes from a retained backup directory. Rollback restores data only; recreate the original index schema separately if the index definition was changed.\n\n**Syntax**\n\n[code example]\n\n**Required Options**\n\n| Option | Description |\n|----------------|-----------------------------------------------------------------|\n| `--backup-dir` | Directory containing vector backup files from a prior migration |\n\n**Example**\n\n[code example]\n\n#### `rvl migrate batch-plan`\n\nGenerate a batch plan that applies one shared schema patch to multiple indexes.\n\n**Syntax**\n\n[code example]\n\n#### `rvl migrate batch-apply`\n\nExecute a batch migration plan and write checkpoint state for resume.\n\n**Syntax**\n\n[code example]\n\n**Required Options**\n\n| Option | Description |\n|----------------|------------------------------------------------------------------------------------------------------------------------------------------------|\n| `--plan` | Path to the batch plan YAML file |\n| `--backup-dir` | Required per-index migration backup directory. Stored in checkpoint state and used for vector backup files when hash vector bytes are mutated. |\n\n**Example**\n\n[code example]\n\n#### `rvl migrate batch-resume`\n\nResume an interrupted batch migration from its checkpoint state.\n\n**Syntax**\n\n[code example]\n\nIf `--backup-dir` is omitted, resume uses the backup directory stored in `batch_state.yaml`. Passing a different backup directory for the same checkpoint is rejected.\n\n#### `rvl migrate batch-status`\n\nShow status for an in-progress or completed batch migration.\n\n**Syntax**\n\n[code example]" }, { "id": "exit-codes", "title": "Exit Codes", "role": "content", "text": "The CLI returns the following exit codes:\n\n| Code | Description |\n|--------|-------------------------------------------------------------------|\n| `0` | Command completed successfully |\n| `1` | Command failed due to missing required arguments or invalid input |" }, { "id": "related-resources", "title": "Related Resources", "role": "related", "text": "- [The RedisVL CLI](https://redis.io/docs/latest/../user_guide/cli) for a tutorial-style walkthrough\n- [Schema](https://redis.io/docs/latest/schema) for YAML schema format details\n- [Search Index Classes](https://redis.io/docs/latest/searchindex) for the Python `SearchIndex` API" } ], "examples": [ { "id": "installation-ex0", "language": "bash", "code": "pip install redisvl", "section_id": "installation" }, { "id": "installation-ex1", "language": "bash", "code": "rvl version", "section_id": "installation" }, { "id": "connection-configuration-ex0", "language": "bash", "code": "export REDIS_URL=\"redis://localhost:6379\"\nrvl index listall", "section_id": "connection-configuration" }, { "id": "connection-configuration-ex1", "language": "bash", "code": "rvl index listall --host myredis.example.com --port 6380", "section_id": "connection-configuration" }, { "id": "connection-configuration-ex2", "language": "bash", "code": "rvl index listall --user admin --password secret --ssl", "section_id": "connection-configuration" }, { "id": "getting-help-ex0", "language": "bash", "code": "# Display top-level help\nrvl --help\n\n# Display help for a command group\nrvl index --help\n\n# Display help for a specific subcommand\nrvl index create --help", "section_id": "getting-help" }, { "id": "rvl-version-ex0", "language": "bash", "code": "rvl version [OPTIONS]", "section_id": "rvl-version" }, { "id": "rvl-version-ex1", "language": "bash", "code": "# Full version output\nrvl version\n\n# Version number only\nrvl version --short", "section_id": "rvl-version" }, { "id": "rvl-index-ex0", "language": "bash", "code": "rvl index [OPTIONS]", "section_id": "rvl-index" }, { "id": "rvl-index-ex1", "language": "bash", "code": "rvl index create -s [CONNECTION_OPTIONS]", "section_id": "rvl-index" }, { "id": "rvl-index-ex2", "language": "bash", "code": "rvl index create -s schema.yaml", "section_id": "rvl-index" }, { "id": "rvl-index-ex3", "language": "yaml", "code": "version: '0.1.0'\n\nindex:\n name: my_index\n prefix: doc\n storage_type: hash\n\nfields:\n - name: content\n type: text\n - name: embedding\n type: vector\n attrs:\n dims: 768\n algorithm: hnsw\n distance_metric: cosine", "section_id": "rvl-index" }, { "id": "rvl-index-ex4", "language": "bash", "code": "rvl index info (-i | -s ) [OPTIONS]", "section_id": "rvl-index" }, { "id": "rvl-index-ex5", "language": "bash", "code": "rvl index info -i my_index", "section_id": "rvl-index" }, { "id": "rvl-index-ex6", "language": "bash", "code": "rvl index listall [CONNECTION_OPTIONS]", "section_id": "rvl-index" }, { "id": "rvl-index-ex7", "language": "bash", "code": "rvl index listall", "section_id": "rvl-index" }, { "id": "rvl-index-ex8", "language": "text", "code": "Indices:\n1. products_index\n2. documents_index\n3. embeddings_index", "section_id": "rvl-index" }, { "id": "rvl-index-ex9", "language": "bash", "code": "rvl index delete (-i | -s ) [CONNECTION_OPTIONS]", "section_id": "rvl-index" }, { "id": "rvl-index-ex10", "language": "bash", "code": "rvl index delete -i my_index", "section_id": "rvl-index" }, { "id": "rvl-index-ex11", "language": "bash", "code": "rvl index destroy (-i | -s ) [CONNECTION_OPTIONS]", "section_id": "rvl-index" }, { "id": "rvl-index-ex12", "language": "bash", "code": "rvl index destroy -i my_index", "section_id": "rvl-index" }, { "id": "rvl-stats-ex0", "language": "bash", "code": "rvl stats (-i | -s ) [OPTIONS]", "section_id": "rvl-stats" }, { "id": "rvl-stats-ex1", "language": "bash", "code": "rvl stats -i my_index", "section_id": "rvl-stats" }, { "id": "rvl-migrate-ex0", "language": "bash", "code": "rvl migrate [OPTIONS]", "section_id": "rvl-migrate" }, { "id": "rvl-migrate-ex1", "language": "bash", "code": "rvl migrate plan --index (--schema-patch | --target-schema ) [OPTIONS]", "section_id": "rvl-migrate" }, { "id": "rvl-migrate-ex2", "language": "bash", "code": "rvl migrate plan -i my_index --schema-patch changes.yaml --plan-out plan.yaml", "section_id": "rvl-migrate" }, { "id": "rvl-migrate-ex3", "language": "bash", "code": "rvl migrate apply --plan --backup-dir [OPTIONS]", "section_id": "rvl-migrate" }, { "id": "rvl-migrate-ex4", "language": "bash", "code": "rvl migrate apply --plan plan.yaml --backup-dir /tmp/backups\nrvl migrate apply --plan plan.yaml --async --backup-dir /tmp/backups --workers 4", "section_id": "rvl-migrate" }, { "id": "rvl-migrate-ex5", "language": "bash", "code": "rvl migrate wizard [--index ] [OPTIONS]", "section_id": "rvl-migrate" }, { "id": "rvl-migrate-ex6", "language": "bash", "code": "rvl migrate wizard -i my_index --plan-out plan.yaml", "section_id": "rvl-migrate" }, { "id": "rvl-migrate-ex7", "language": "bash", "code": "rvl migrate rollback --backup-dir [--index ] [OPTIONS]", "section_id": "rvl-migrate" }, { "id": "rvl-migrate-ex8", "language": "bash", "code": "rvl migrate rollback --backup-dir /tmp/backups --index my_index", "section_id": "rvl-migrate" }, { "id": "rvl-migrate-ex9", "language": "bash", "code": "rvl migrate batch-plan --schema-patch (--pattern | --indexes | --indexes-file ) [OPTIONS]", "section_id": "rvl-migrate" }, { "id": "rvl-migrate-ex10", "language": "bash", "code": "rvl migrate batch-apply --plan --backup-dir [OPTIONS]", "section_id": "rvl-migrate" }, { "id": "rvl-migrate-ex11", "language": "bash", "code": "rvl migrate batch-apply --plan batch_plan.yaml --backup-dir /tmp/backups", "section_id": "rvl-migrate" }, { "id": "rvl-migrate-ex12", "language": "bash", "code": "rvl migrate batch-resume --state [--plan ] [--retry-failed] [--backup-dir ]", "section_id": "rvl-migrate" }, { "id": "rvl-migrate-ex13", "language": "bash", "code": "rvl migrate batch-status --state ", "section_id": "rvl-migrate" } ] }