# Command Line Interface

```json metadata
{
  "schema_version": 2,
  "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
```

> [!NOTE]
> `listall` uses `FT._LIST`, which Redis tags `@admin` as well as `@search`.
> An ACL that grants search access and then subtracts `@admin`, such as
> `+@search -@admin`, denies this command with a permission error even though the
> rest of the CLI works. The migration commands that discover indexes for you are
> denied by the same ACL: `rvl migrate helper`, `rvl migrate wizard` when no
> `-i/--index` is given, and `rvl migrate batch-plan --pattern`. See
> [Install RedisVL](https://redis.io/docs/latest/../user_guide/installation).

#### `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
```

> [!WARNING]
> 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`

> [!WARNING]
> 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.

> [!WARNING]
> 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