gh-jezweb-claude-skills-skills-cloudflare-vectorize/references/wrangler-commands.md

Wrangler Vectorize Commands Reference

Complete CLI reference for managing Cloudflare Vectorize indexes with Wrangler.

Minimum Version Required: Wrangler 3.71.0+

Index Management

create

Create a new Vectorize index.

⚠️ CRITICAL: Dimensions and metric cannot be changed after creation!

npx wrangler vectorize create <INDEX_NAME> \
  --dimensions=<NUMBER> \
  --metric=<METRIC> \
  [--description=<TEXT>]

Parameters:

• INDEX_NAME (required): Name of the index (lowercase, alphanumeric, dashes, max 32 chars)
• --dimensions (required): Vector width (768 for Workers AI bge-base, 1536 for OpenAI small, 3072 for OpenAI large)
• --metric (required): Distance metric (cosine, euclidean, or dot-product)
• --description (optional): Human-readable description

Examples:

# Workers AI @cf/baai/bge-base-en-v1.5 (768 dimensions)
npx wrangler vectorize create docs-search \
  --dimensions=768 \
  --metric=cosine \
  --description="Documentation semantic search"

# OpenAI text-embedding-3-small (1536 dimensions)
npx wrangler vectorize create product-recs \
  --dimensions=1536 \
  --metric=cosine

# OpenAI text-embedding-3-large (3072 dimensions)
npx wrangler vectorize create high-accuracy-index \
  --dimensions=3072 \
  --metric=euclidean

list

List all Vectorize indexes in your account.

npx wrangler vectorize list

Output: Table with index names, dimensions, and distance metrics.

get

Get details about a specific index.

npx wrangler vectorize get <INDEX_NAME>

Returns: Index configuration (name, dimensions, metric, description).

info

Get additional information about an index.

npx wrangler vectorize info <INDEX_NAME>

Returns: Vector count, last processed mutation, index status.

delete

Delete a Vectorize index (irreversible!).

npx wrangler vectorize delete <INDEX_NAME> [--force]

Parameters:

• --force (optional): Skip confirmation prompt

Example:

npx wrangler vectorize delete old-index --force

Metadata Indexes

⚠️ CRITICAL: Create metadata indexes BEFORE inserting vectors! Vectors added before a metadata index exists won't be filterable on that property.

create-metadata-index

Enable metadata filtering on a specific property.

npx wrangler vectorize create-metadata-index <INDEX_NAME> \
  --property-name=<PROPERTY> \
  --type=<TYPE>

Parameters:

• INDEX_NAME (required): Vectorize index name
• --property-name (required): Metadata field name
• --type (required): Data type (string, number, or boolean)

Limits:

• Max 10 metadata indexes per Vectorize index
• String indexes: First 64 bytes (UTF-8)
• Number indexes: Float64 precision

Examples:

# String metadata (category filtering)
npx wrangler vectorize create-metadata-index docs-search \
  --property-name=category \
  --type=string

# Number metadata (timestamp filtering)
npx wrangler vectorize create-metadata-index docs-search \
  --property-name=published_at \
  --type=number

# Boolean metadata (published status)
npx wrangler vectorize create-metadata-index docs-search \
  --property-name=published \
  --type=boolean

# Nested metadata (use dot notation)
npx wrangler vectorize create-metadata-index docs-search \
  --property-name=author_verified \
  --type=boolean

list-metadata-index

List all metadata indexes for an index.

npx wrangler vectorize list-metadata-index <INDEX_NAME>

Output: Table with property names and types.

delete-metadata-index

Disable metadata filtering on a property.

npx wrangler vectorize delete-metadata-index <INDEX_NAME> \
  --property-name=<PROPERTY>

Example:

npx wrangler vectorize delete-metadata-index docs-search \
  --property-name=category

Vector Operations

insert

Insert vectors from a file (NDJSON format).

npx wrangler vectorize insert <INDEX_NAME> \
  --file=<PATH>

File Format (NDJSON - one JSON object per line):

{"id":"1","values":[0.1,0.2,0.3],"metadata":{"title":"Doc 1"}}
{"id":"2","values":[0.4,0.5,0.6],"metadata":{"title":"Doc 2"}}

Example:

npx wrangler vectorize insert docs-search --file=vectors.ndjson

query

Query vectors directly from CLI.

npx wrangler vectorize query <INDEX_NAME> \
  --vector="[<COMMA_SEPARATED_FLOATS>]" \
  [--top-k=<NUMBER>] \
  [--return-metadata=<MODE>] \
  [--namespace=<NAMESPACE>] \
  [--filter=<JSON>]

Parameters:

• --vector (required): Query vector as JSON array
• --top-k (optional): Number of results (default: 10)
• --return-metadata (optional): none, indexed, or all (default: none)
• --namespace (optional): Query specific namespace
• --filter (optional): Metadata filter as JSON string

Examples:

# Simple query
npx wrangler vectorize query docs-search \
  --vector="[0.1,0.2,0.3,...]" \
  --top-k=5 \
  --return-metadata=all

# Query with filter
npx wrangler vectorize query docs-search \
  --vector="[0.1,0.2,...]" \
  --filter='{"category":"documentation","published":true}' \
  --top-k=3

# Query specific namespace
npx wrangler vectorize query docs-search \
  --vector="[0.1,0.2,...]" \
  --namespace="customer-123" \
  --top-k=5

list-vectors

List vector IDs in paginated manner.

npx wrangler vectorize list-vectors <INDEX_NAME> \
  [--count=<NUMBER>] \
  [--cursor=<CURSOR>]

Parameters:

• --count (optional): Vectors per page (1-1000, default: 100)
• --cursor (optional): Pagination cursor from previous response

Example:

# Get first 100 vector IDs
npx wrangler vectorize list-vectors docs-search --count=100

# Get next page (use cursor from previous response)
npx wrangler vectorize list-vectors docs-search \
  --count=100 \
  --cursor="abc123..."

get-vectors

Fetch specific vectors by ID.

npx wrangler vectorize get-vectors <INDEX_NAME> \
  --ids=<ID1,ID2,ID3>

Example:

npx wrangler vectorize get-vectors docs-search \
  --ids="doc-1,doc-2,doc-3"

delete-vectors

Delete vectors by ID.

npx wrangler vectorize delete-vectors <INDEX_NAME> \
  --ids=<ID1,ID2,ID3>

Example:

npx wrangler vectorize delete-vectors docs-search \
  --ids="old-doc-1,old-doc-2"

Common Workflows

Initial Setup

# 1. Create index
npx wrangler vectorize create my-index \
  --dimensions=768 \
  --metric=cosine

# 2. Create metadata indexes (BEFORE inserting!)
npx wrangler vectorize create-metadata-index my-index \
  --property-name=category --type=string

npx wrangler vectorize create-metadata-index my-index \
  --property-name=timestamp --type=number

# 3. Verify metadata indexes
npx wrangler vectorize list-metadata-index my-index

# 4. Now safe to insert vectors (via Worker or CLI)

Bulk Data Import

# Prepare NDJSON file
cat > vectors.ndjson << 'EOF'
{"id":"doc-1","values":[0.1,0.2,0.3,...],"metadata":{"category":"docs"}}
{"id":"doc-2","values":[0.4,0.5,0.6,...],"metadata":{"category":"tutorials"}}
EOF

# Import
npx wrangler vectorize insert my-index --file=vectors.ndjson

# Verify
npx wrangler vectorize info my-index

Debug / Inspect

# Check index configuration
npx wrangler vectorize get my-index

# Check vector count
npx wrangler vectorize info my-index

# List some vector IDs
npx wrangler vectorize list-vectors my-index --count=10

# Inspect specific vectors
npx wrangler vectorize get-vectors my-index --ids="doc-1,doc-2"

# Test query
npx wrangler vectorize query my-index \
  --vector="[0.1,0.2,...]" \
  --top-k=3 \
  --return-metadata=all

Cleanup

# Delete specific vectors
npx wrangler vectorize delete-vectors my-index --ids="doc-1,doc-2"

# Delete entire index (irreversible!)
npx wrangler vectorize delete my-index --force

Tips & Best Practices

1. Always use latest Wrangler: npx wrangler@latest vectorize ...
2. Create metadata indexes first: Before any vector insertion
3. Test with small data: Use --count=10 when listing/testing
4. Batch operations: Use Workers for bulk operations (faster than CLI)
5. Monitor vector count: Use info command to track index size
6. Verify before delete: Always check with get before delete

Error Messages

Error	Cause	Solution
"Wrangler version 3.71.0 required"	Old Wrangler	Update: npm install -g wrangler@latest
"Vector dimensions do not match"	Wrong embedding size	Check model output dimensions
"Metadata property not indexed"	Metadata index missing	Create metadata index before querying
"Index name already exists"	Duplicate name	Use different name or delete old index
"Invalid filter syntax"	Malformed JSON filter	Check JSON syntax and operators

See Also

• Index Operations
• Vector Operations
• Metadata Guide
• Official Wrangler Docs