# Command Line Interface

```json metadata
{
  "title": "Command Line Interface",
  "description": "",
  "categories": null,
  "tableOfContents": {"sections":[{"id":"installation","title":"Installation"},{"id":"connection-configuration","title":"Connection Configuration"},{"id":"getting-help","title":"Getting Help"},{"children":[{"id":"rvl-version","title":"rvl version"},{"id":"rvl-index","title":"rvl index"},{"id":"rvl-stats","title":"rvl stats"},{"id":"rvl-migrate","title":"rvl migrate"}],"id":"commands","title":"Commands"},{"id":"exit-codes","title":"Exit Codes"},{"id":"related-resources","title":"Related Resources"}]}

,
  "codeExamples": []
}
```

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.

## Installation

The `rvl` command is included when you install RedisVL.

```bash
pip install redisvl
```

Verify the installation by running:

```bash
rvl version
```

## Connection Configuration

The CLI connects to Redis using the following resolution order:

1. The `REDIS_URL` environment variable, if set
2. Explicit connection flags (`--host`, `--port`, `--url`)
3. Default values (`localhost:6379`)

**Connection Flags**

All commands that interact with Redis accept these optional flags:

| Flag               | Type    | Description                                     | Default     |
|--------------------|---------|-------------------------------------------------|-------------|
| `-u`, `--url`      | string  | Full Redis URL (e.g., `redis://localhost:6379`) | None        |
| `--host`           | string  | Redis server hostname                           | `localhost` |
| `-p`, `--port`     | integer | Redis server port                               | `6379`      |
| `--user`           | string  | Redis username for authentication               | `default`   |
| `-a`, `--password` | string  | Redis password for authentication               | Empty       |
| `--ssl`            | flag    | Enable SSL/TLS encryption                       | Disabled    |

**Examples**

Connect using environment variable:

```bash
export REDIS_URL="redis://localhost:6379"
rvl index listall
```

Connect with explicit host and port:

```bash
rvl index listall --host myredis.example.com --port 6380
```

Connect with authentication and SSL:

```bash
rvl index listall --user admin --password secret --ssl
```

## Getting Help

All commands support the `-h` and `--help` flags to display usage information.

| Flag           | Description                               |
|----------------|-------------------------------------------|
| `-h`, `--help` | Display usage information for the command |

**Examples**

```bash
# Display top-level help
rvl --help

# Display help for a command group
rvl index --help

# Display help for a specific subcommand
rvl index create --help
```

Running `rvl` without any arguments also displays the top-level help message.

## Commands

### `rvl version`

Display the installed RedisVL version.

**Syntax**

```bash
rvl version [OPTIONS]
```

**Options**

| Option          | Description                                                 |
|-----------------|-------------------------------------------------------------|
| `-s`, `--short` | Print only the version number without additional formatting |

**Examples**

```bash
# Full version output
rvl version

# Version number only
rvl version --short
```

### `rvl index`

Manage vector search indices. This command group provides subcommands for creating, inspecting, listing, and removing indices.

**Syntax**

```bash
rvl index <subcommand> [OPTIONS]
```

**Subcommands**

| Subcommand   | Description                                          |
|--------------|------------------------------------------------------|
| `create`     | Create a new index from a YAML schema file           |
| `info`       | Display detailed information about an index          |
| `listall`    | List all existing indices in the Redis instance      |
| `delete`     | Remove an index while preserving the underlying data |
| `destroy`    | Remove an index and delete all associated data       |

#### `rvl index create`

Create a new vector search index from a YAML schema definition.

**Syntax**

```bash
rvl index create -s <schema_file> [CONNECTION_OPTIONS]
```

**Required Options**

| Option           | Description                                               |
|------------------|-----------------------------------------------------------|
| `-s`, `--schema` | Path to the YAML schema file defining the index structure |

**Example**

```bash
rvl index create -s schema.yaml
```

**Schema File Format**

The schema file must be valid YAML with the following structure:

```yaml
version: '0.1.0'

index:
    name: my_index
    prefix: doc
    storage_type: hash

fields:
    - name: content
      type: text
    - name: embedding
      type: vector
      attrs:
        dims: 768
        algorithm: hnsw
        distance_metric: cosine
```

#### `rvl index info`

Display detailed information about an existing index, including field definitions and index options.

**Syntax**

```bash
rvl index info (-i <index_name> | -s <schema_file>) [OPTIONS]
```

**Options**

| Option           | Description                                                    |
|------------------|----------------------------------------------------------------|
| `-i`, `--index`  | Name of the index to inspect                                   |
| `-s`, `--schema` | Path to the schema file (alternative to specifying index name) |

**Example**

```bash
rvl index info -i my_index
```

**Output**

The command displays two tables:

1. **Index Information** containing the index name, storage type, key prefixes, index options, and indexing status
2. **Index Fields** listing each field with its name, attribute, type, and any additional field options

#### `rvl index listall`

List all vector search indices in the connected Redis instance.

**Syntax**

```bash
rvl index listall [CONNECTION_OPTIONS]
```

**Example**

```bash
rvl index listall
```

**Output**

Returns a numbered list of all index names:

```text
Indices:
1. products_index
2. documents_index
3. embeddings_index
```

#### `rvl index delete`

Remove 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.

**Syntax**

```bash
rvl index delete (-i <index_name> | -s <schema_file>) [CONNECTION_OPTIONS]
```

**Options**

| Option           | Description                                                    |
|------------------|----------------------------------------------------------------|
| `-i`, `--index`  | Name of the index to delete                                    |
| `-s`, `--schema` | Path to the schema file (alternative to specifying index name) |

**Example**

```bash
rvl index delete -i my_index
```

#### `rvl index destroy`

Remove an index and permanently delete all associated data from Redis. This operation cannot be undone.

**Syntax**

```bash
rvl index destroy (-i <index_name> | -s <schema_file>) [CONNECTION_OPTIONS]
```

**Options**

| Option           | Description                                                    |
|------------------|----------------------------------------------------------------|
| `-i`, `--index`  | Name of the index to destroy                                   |
| `-s`, `--schema` | Path to the schema file (alternative to specifying index name) |

**Example**

```bash
rvl index destroy -i my_index
```


This command permanently deletes both the index and all documents stored with the index prefix. Ensure you have backups before running this command.


### `rvl stats`

Display statistics about an existing index, including document counts, memory usage, and indexing performance metrics.

**Syntax**

```bash
rvl stats (-i <index_name> | -s <schema_file>) [OPTIONS]
```

**Options**

| Option           | Description                                                    |
|------------------|----------------------------------------------------------------|
| `-i`, `--index`  | Name of the index to query                                     |
| `-s`, `--schema` | Path to the schema file (alternative to specifying index name) |

**Example**

```bash
rvl stats -i my_index
```

**Statistics Reference**

The command returns the following metrics:

| Metric                        | Description                                |
|-------------------------------|--------------------------------------------|
| `num_docs`                    | Total number of indexed documents          |
| `num_terms`                   | Number of distinct terms in text fields    |
| `max_doc_id`                  | Highest internal document ID               |
| `num_records`                 | Total number of index records              |
| `percent_indexed`             | Percentage of documents fully indexed      |
| `hash_indexing_failures`      | Number of documents that failed to index   |
| `number_of_uses`              | Number of times the index has been queried |
| `bytes_per_record_avg`        | Average bytes per index record             |
| `doc_table_size_mb`           | Document table size in megabytes           |
| `inverted_sz_mb`              | Inverted index size in megabytes           |
| `key_table_size_mb`           | Key table size in megabytes                |
| `offset_bits_per_record_avg`  | Average offset bits per record             |
| `offset_vectors_sz_mb`        | Offset vectors size in megabytes           |
| `offsets_per_term_avg`        | Average offsets per term                   |
| `records_per_doc_avg`         | Average records per document               |
| `sortable_values_size_mb`     | Sortable values size in megabytes          |
| `total_indexing_time`         | Total time spent indexing in milliseconds  |
| `total_inverted_index_blocks` | Number of inverted index blocks            |
| `vector_index_sz_mb`          | Vector index size in megabytes             |

### `rvl migrate`


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.


Manage document-preserving index migrations. This command group provides subcommands for planning, executing, and validating schema migrations that preserve existing data.

**Syntax**

```bash
rvl migrate <subcommand> [OPTIONS]
```

**Subcommands**

| Subcommand     | Description                                                    |
|----------------|----------------------------------------------------------------|
| `helper`       | Show migration guidance and supported capabilities             |
| `wizard`       | Interactively build a migration plan and schema patch          |
| `plan`         | Generate a migration plan from a schema patch or target schema |
| `apply`        | Execute a reviewed drop/recreate migration plan                |
| `estimate`     | Estimate disk space required for a migration (dry-run)         |
| `rollback`     | Restore original vectors from a backup directory               |
| `validate`     | Validate a completed migration against the live index          |
| `batch-plan`   | Generate a batch migration plan for multiple indexes           |
| `batch-apply`  | Execute a batch migration plan with state tracking             |
| `batch-resume` | Resume an interrupted batch migration                          |
| `batch-status` | Show status of an in-progress or completed batch migration     |

#### `rvl migrate plan`

Generate a migration plan for a document-preserving drop/recreate migration.

**Syntax**

```bash
rvl migrate plan --index <name> (--schema-patch <patch.yaml> | --target-schema <schema.yaml>) [OPTIONS]
```

**Required Options**

| Option            | Description                                                                       |
|-------------------|-----------------------------------------------------------------------------------|
| `--index`, `-i`   | Name of the source index to migrate                                               |
| `--schema-patch`  | Path to a YAML schema patch file (mutually exclusive with `--target-schema`)      |
| `--target-schema` | Path to a full target schema YAML file (mutually exclusive with `--schema-patch`) |

**Optional Options**

| Option       | Description                                                              |
|--------------|--------------------------------------------------------------------------|
| `--plan-out` | Output path for the migration plan YAML (default: `migration_plan.yaml`) |

**Example**

```bash
rvl migrate plan -i my_index --schema-patch changes.yaml --plan-out plan.yaml
```

#### `rvl migrate apply`

Execute a reviewed drop/recreate migration plan. Use `--async` for large migrations involving vector quantization.


Hash vector quantization is unsupported when the same Redis keys are also
indexed by another live RediSearch index that expects the old vector
datatype. Quantization rewrites vector bytes in the document key itself, so
other indexes covering the same key may drop the document or fail to index
it. Use an application-level migration with new keys or fields when
documents are shared across indexes.


**Syntax**

```bash
rvl migrate apply --plan <migration_plan.yaml> --backup-dir <dir> [OPTIONS]
```

**Required Options**

| Option         | Description                                                                                                                                                                                                    |
|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--plan`       | Path to the migration plan YAML file                                                                                                                                                                           |
| `--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. |

**Optional Options**

| Option               | Description                                                            |
|----------------------|------------------------------------------------------------------------|
| `--async`            | Run migration asynchronously (recommended for large quantization jobs) |
| `--batch-size`       | Keys per pipeline batch (default 500)                                  |
| `--workers`          | Number of parallel workers for quantization (default 1).               |
| `--query-check-file` | Path to a YAML file with post-migration query checks                   |

**Example**

```bash
rvl migrate apply --plan plan.yaml --backup-dir /tmp/backups
rvl migrate apply --plan plan.yaml --async --backup-dir /tmp/backups --workers 4
```

#### `rvl migrate wizard`

Interactively build a schema patch and migration plan through a guided wizard.

**Syntax**

```bash
rvl migrate wizard [--index <name>] [OPTIONS]
```

**Example**

```bash
rvl migrate wizard -i my_index --plan-out plan.yaml
```

#### `rvl migrate rollback`

Restore original vector bytes from a retained backup directory. Rollback restores data only; recreate the original index schema separately if the index definition was changed.

**Syntax**

```bash
rvl migrate rollback --backup-dir <dir> [--index <name>] [OPTIONS]
```

**Required Options**

| Option         | Description                                                     |
|----------------|-----------------------------------------------------------------|
| `--backup-dir` | Directory containing vector backup files from a prior migration |

**Example**

```bash
rvl migrate rollback --backup-dir /tmp/backups --index my_index
```

#### `rvl migrate batch-plan`

Generate a batch plan that applies one shared schema patch to multiple indexes.

**Syntax**

```bash
rvl migrate batch-plan --schema-patch <patch.yaml> (--pattern <glob> | --indexes <name1,name2> | --indexes-file <file>) [OPTIONS]
```

#### `rvl migrate batch-apply`

Execute a batch migration plan and write checkpoint state for resume.

**Syntax**

```bash
rvl migrate batch-apply --plan <batch_plan.yaml> --backup-dir <dir> [OPTIONS]
```

**Required Options**

| Option         | Description                                                                                                                                    |
|----------------|------------------------------------------------------------------------------------------------------------------------------------------------|
| `--plan`       | Path to the batch plan YAML file                                                                                                               |
| `--backup-dir` | Required per-index migration backup directory. Stored in checkpoint state and used for vector backup files when hash vector bytes are mutated. |

**Example**

```bash
rvl migrate batch-apply --plan batch_plan.yaml --backup-dir /tmp/backups
```

#### `rvl migrate batch-resume`

Resume an interrupted batch migration from its checkpoint state.

**Syntax**

```bash
rvl migrate batch-resume --state <batch_state.yaml> [--plan <batch_plan.yaml>] [--retry-failed] [--backup-dir <dir>]
```

If `--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.

#### `rvl migrate batch-status`

Show status for an in-progress or completed batch migration.

**Syntax**

```bash
rvl migrate batch-status --state <batch_state.yaml>
```

## Exit Codes

The CLI returns the following exit codes:

| Code   | Description                                                       |
|--------|-------------------------------------------------------------------|
| `0`    | Command completed successfully                                    |
| `1`    | Command failed due to missing required arguments or invalid input |

## Related Resources

- [The RedisVL CLI](https://redis.io/docs/latest/../user_guide/cli) for a tutorial-style walkthrough
- [Schema](https://redis.io/docs/latest/schema) for YAML schema format details
- [Search Index Classes](https://redis.io/docs/latest/searchindex) for the Python `SearchIndex` API