{
  "id": "cli",
  "title": "Command Line Interface",
  "url": "https://redis.io/docs/latest/develop/ai/redisvl/0.20.0/api/cli/",
  "summary": "",
  "content": "\n\nRedisVL 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.\n\n## Installation\n\nThe `rvl` command is included when you install RedisVL.\n\n```bash\npip install redisvl\n```\n\nVerify the installation by running:\n\n```bash\nrvl version\n```\n\n## Connection Configuration\n\nThe 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```bash\nexport REDIS_URL=\"redis://localhost:6379\"\nrvl index listall\n```\n\nConnect with explicit host and port:\n\n```bash\nrvl index listall --host myredis.example.com --port 6380\n```\n\nConnect with authentication and SSL:\n\n```bash\nrvl index listall --user admin --password secret --ssl\n```\n\n## Getting Help\n\nAll 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```bash\n# 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\n```\n\nRunning `rvl` without any arguments also displays the top-level help message.\n\n## Commands\n\n### `rvl version`\n\nDisplay the installed RedisVL version.\n\n**Syntax**\n\n```bash\nrvl version [OPTIONS]\n```\n\n**Options**\n\n| Option          | Description                                                 |\n|-----------------|-------------------------------------------------------------|\n| `-s`, `--short` | Print only the version number without additional formatting |\n\n**Examples**\n\n```bash\n# Full version output\nrvl version\n\n# Version number only\nrvl version --short\n```\n\n### `rvl index`\n\nManage vector search indices. This command group provides subcommands for creating, inspecting, listing, and removing indices.\n\n**Syntax**\n\n```bash\nrvl index \u003csubcommand\u003e [OPTIONS]\n```\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```bash\nrvl index create -s \u003cschema_file\u003e [CONNECTION_OPTIONS]\n```\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```bash\nrvl index create -s schema.yaml\n```\n\n**Schema File Format**\n\nThe schema file must be valid YAML with the following structure:\n\n```yaml\nversion: '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\n```\n\n#### `rvl index info`\n\nDisplay detailed information about an existing index, including field definitions and index options.\n\n**Syntax**\n\n```bash\nrvl index info (-i \u003cindex_name\u003e | -s \u003cschema_file\u003e) [OPTIONS]\n```\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```bash\nrvl index info -i my_index\n```\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```bash\nrvl index listall [CONNECTION_OPTIONS]\n```\n\n**Example**\n\n```bash\nrvl index listall\n```\n\n**Output**\n\nReturns a numbered list of all index names:\n\n```text\nIndices:\n1. products_index\n2. documents_index\n3. embeddings_index\n```\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```bash\nrvl index delete (-i \u003cindex_name\u003e | -s \u003cschema_file\u003e) [CONNECTION_OPTIONS]\n```\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```bash\nrvl index delete -i my_index\n```\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```bash\nrvl index destroy (-i \u003cindex_name\u003e | -s \u003cschema_file\u003e) [CONNECTION_OPTIONS]\n```\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```bash\nrvl index destroy -i my_index\n```\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.\n\n\n### `rvl stats`\n\nDisplay statistics about an existing index, including document counts, memory usage, and indexing performance metrics.\n\n**Syntax**\n\n```bash\nrvl stats (-i \u003cindex_name\u003e | -s \u003cschema_file\u003e) [OPTIONS]\n```\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```bash\nrvl stats -i my_index\n```\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             |\n\n### `rvl migrate`\n\n\nThe 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```bash\nrvl migrate \u003csubcommand\u003e [OPTIONS]\n```\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```bash\nrvl migrate plan --index \u003cname\u003e (--schema-patch \u003cpatch.yaml\u003e | --target-schema \u003cschema.yaml\u003e) [OPTIONS]\n```\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```bash\nrvl migrate plan -i my_index --schema-patch changes.yaml --plan-out plan.yaml\n```\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```bash\nrvl migrate apply --plan \u003cmigration_plan.yaml\u003e --backup-dir \u003cdir\u003e [OPTIONS]\n```\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```bash\nrvl migrate apply --plan plan.yaml --backup-dir /tmp/backups\nrvl migrate apply --plan plan.yaml --async --backup-dir /tmp/backups --workers 4\n```\n\n#### `rvl migrate wizard`\n\nInteractively build a schema patch and migration plan through a guided wizard.\n\n**Syntax**\n\n```bash\nrvl migrate wizard [--index \u003cname\u003e] [OPTIONS]\n```\n\n**Example**\n\n```bash\nrvl migrate wizard -i my_index --plan-out plan.yaml\n```\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```bash\nrvl migrate rollback --backup-dir \u003cdir\u003e [--index \u003cname\u003e] [OPTIONS]\n```\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```bash\nrvl migrate rollback --backup-dir /tmp/backups --index my_index\n```\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```bash\nrvl migrate batch-plan --schema-patch \u003cpatch.yaml\u003e (--pattern \u003cglob\u003e | --indexes \u003cname1,name2\u003e | --indexes-file \u003cfile\u003e) [OPTIONS]\n```\n\n#### `rvl migrate batch-apply`\n\nExecute a batch migration plan and write checkpoint state for resume.\n\n**Syntax**\n\n```bash\nrvl migrate batch-apply --plan \u003cbatch_plan.yaml\u003e --backup-dir \u003cdir\u003e [OPTIONS]\n```\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```bash\nrvl migrate batch-apply --plan batch_plan.yaml --backup-dir /tmp/backups\n```\n\n#### `rvl migrate batch-resume`\n\nResume an interrupted batch migration from its checkpoint state.\n\n**Syntax**\n\n```bash\nrvl migrate batch-resume --state \u003cbatch_state.yaml\u003e [--plan \u003cbatch_plan.yaml\u003e] [--retry-failed] [--backup-dir \u003cdir\u003e]\n```\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```bash\nrvl migrate batch-status --state \u003cbatch_state.yaml\u003e\n```\n\n## Exit Codes\n\nThe 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 |\n\n## Related Resources\n\n- [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\n",
  "tags": [],
  "last_updated": "2026-06-11T16:10:09-04:00"
}