Command Line Interface#

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.

pip install redisvl

Verify the installation by running:

rvl version

Connection Configuration#

The CLI connects to Redis using the following resolution order:

The REDIS_URL environment variable, if set
Explicit connection flags (--host, --port, --url)
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:

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

Connect with explicit host and port:

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

Connect with authentication and SSL:

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

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

Tip

For a hands-on tutorial with practical examples, see the The RedisVL CLI.

Commands#

rvl version#

Display the installed RedisVL version.

Syntax

rvl version [OPTIONS]

Options

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

Examples

# 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

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

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

rvl index create -s schema.yaml

Schema File Format

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

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

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

rvl index info -i my_index

Output

The command displays two tables:

Index Information containing the index name, storage type, key prefixes, index options, and indexing status
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

rvl index listall [CONNECTION_OPTIONS]

Example

rvl index listall

Output

Returns a numbered list of all index names:

Indices:
products_index
documents_index
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

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

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

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

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

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

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

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

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

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

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

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

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

Example

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

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

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

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

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

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

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

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

Command Line Interface

Contents

Command Line Interface#

Installation#

Connection Configuration#

Getting Help#

Commands#

rvl version#

rvl index#

rvl index create#

rvl index info#

rvl index listall#

rvl index delete#

rvl index destroy#

rvl stats#

rvl migrate#

rvl migrate plan#

rvl migrate apply#

rvl migrate wizard#

rvl migrate rollback#

rvl migrate batch-plan#

rvl migrate batch-apply#

rvl migrate batch-resume#

rvl migrate batch-status#

Exit Codes#

Related Resources#