{ "id": "cli", "title": "Command Line Interface", "url": "https://redis.io/docs/latest/develop/ai/redisvl/api/cli/", "summary": "", "tags": [], "last_updated": "2026-06-11T16:10:09-04:00", "page_type": "content", "content_hash": "94328870defb0c942d7f4861970dea82ad0538449a45eba13645d63a1b7c5845", "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#### `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\nThis 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": "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\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\nHash vector quantization is unsupported when the same Redis keys are also\nindexed by another live RediSearch index that expects the old vector\ndatatype. Quantization rewrites vector bytes in the document key itself, so\nother indexes covering the same key may drop the document or fail to index\nit. Use an application-level migration with new keys or fields when\ndocuments are shared across indexes.\n\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" } ] }