operating-weaviate-cli

name

operating-weaviate-cli

description

Operates Weaviate vector databases through the weaviate-cli tool. Use this skill whenever "weaviate-cli" appears in the prompt, or when the user wants to interact with a running Weaviate cluster. Trigger if the request: mentions weaviate-cli explicitly; asks to create, query, update, or delete collections, tenants, or data in Weaviate; needs to manage RBAC roles and users; wants to run, restore, or cancel backups; asks about cluster health, node status, or shards; needs to manage replication or aliases; wants to benchmark a Weaviate cluster; or is testing/verifying Weaviate functionality from the command line (even if the primary task is testing code changes). Do NOT use for developing or modifying the weaviate-cli source code — use contributing-to-weaviate-cli for that.

Operating weaviate-cli

Manage Weaviate vector databases through the weaviate-cli command-line tool.

Prerequisites

Install the CLI:

pip install weaviate-cli
# or
brew install weaviate/tap/weaviate-cli

Verify connectivity:

weaviate-cli get nodes --minimal --json

Configuration

The CLI reads configuration from ~/.config/weaviate/config.json by default. Use --config-file <path> to override.

Local development (no config needed): The CLI defaults to localhost:8080 (HTTP) and localhost:50051 (gRPC). No config file is required for local clusters.

When authentication is needed, create a config file under ~/.config/weaviate/ with a descriptive filename:

# API key auth
cat > ~/.config/weaviate/cloud-staging.json << 'EOF'
{
    "host": "https://your-cluster.weaviate.cloud",
    "auth": {
        "type": "api_key",
        "api_key": "your-api-key"
    }
}
EOF
weaviate-cli --config-file ~/.config/weaviate/cloud-staging.json get nodes --minimal --json

# RBAC / per-user auth (requires --user flag on every command)
cat > ~/.config/weaviate/local-rbac.json << 'EOF'
{
    "host": "localhost",
    "http_port": "8080",
    "grpc_port": "50051",
    "auth": {
        "type": "user",
        "admin-user": "admin-key",
        "readonly-user": "readonly-key"
    }
}
EOF
weaviate-cli --config-file ~/.config/weaviate/local-rbac.json --user admin-user get nodes --minimal --json

# Custom host with separate gRPC endpoint
cat > ~/.config/weaviate/custom-host.json << 'EOF'
{
    "host": "https://custom-host.example.com",
    "grpc_host": "https://custom-grpc.example.com",
    "http_port": 443,
    "grpc_port": 443,
    "auth": {
        "type": "api_key",
        "api_key": "your-api-key"
    }
}
EOF

Config management rules

• Never overwrite ~/.config/weaviate/config.json without explicit user consent.
• When creating configs for the agent, use descriptive filenames (e.g., local-rbac.json, cloud-prod.json).
• If the user's prompt specifies a config file, use it. Otherwise, assume local defaults (no --config-file).
• Always verify connectivity after creating or switching configs: weaviate-cli [--config-file ...] get nodes --minimal --json

Command Syntax

weaviate-cli [--config-file FILE] [--user USER] <group> <command> [--json] [options]

Global Options

Option	Description
--config-file <path>	Path to config JSON file (overrides default)
--user <name>	User for RBAC-enabled clusters (required when auth type is user)
--version	Print CLI version
--json	Output in JSON format (use on every command for agent-friendly output)

Command Groups

Group	Description
create	Create collections, tenants, data, backups, exports, roles, users, aliases, replications
get	Inspect collections, tenants, shards, backups, exports, roles, users, nodes, aliases, replications
update	Update collections, tenants, shards, data, users, aliases
delete	Delete collections, tenants, data, roles, users, aliases, replications
query	Query data (fetch/vector/keyword/hybrid/uuid), replications, sharding state
restore	Restore backups
cancel	Cancel backups, exports, and replications
assign	Assign roles to users, permissions to roles
revoke	Revoke roles from users, permissions from roles
benchmark	Run QPS benchmarks

Command Reference

Always use --json for programmatic consumption.

Collections

weaviate-cli create collection --collection MyCollection --replication_factor 3 --vector_index hnsw --vectorizer none --json
weaviate-cli get collection --json                          # List all
weaviate-cli get collection --collection MyCollection --json # Specific
weaviate-cli update collection --collection MyCollection --description "Updated" --replication_factor 5 --json
weaviate-cli delete collection --collection MyCollection --json
weaviate-cli delete collection --all --json

Key create options: --multitenant, --auto_tenant_creation, --auto_tenant_activation, --shards N, --vectorizer <type>, --named_vector, --replication_deletion_strategy, --async_replication_config key=value (repeatable; requires --async_enabled and Weaviate >= v1.36.0), --object_ttl_type, --object_ttl_time, --object_ttl_filter_expired, --object_ttl_property_name (only when object_ttl_type=property)

Mutable fields: --async_enabled, --replication_factor, --vector_index, --description, --training_limit, --auto_tenant_creation, --auto_tenant_activation, --replication_deletion_strategy, --async_replication_config key=value (repeatable), --object_ttl_type, --object_ttl_time, --object_ttl_filter_expired, --object_ttl_property_name (only when object_ttl_type=property)

Async Replication Config

# Create with async replication tuning (requires --async_enabled and Weaviate >= v1.36.0)
weaviate-cli create collection --collection MyCol --async_enabled \
  --async_replication_config max_workers=10 \
  --async_replication_config frequency=60 \
  --async_replication_config propagation_concurrency=4 --json

# Update async replication config on existing collection
weaviate-cli update collection --collection MyCol \
  --async_replication_config max_workers=20 \
  --async_replication_config propagation_batch_size=100 --json

Valid keys (all integers): max_workers, hashtree_height, frequency, frequency_while_propagating, alive_nodes_checking_frequency, logging_frequency, diff_batch_size, diff_per_node_timeout, pre_propagation_timeout, propagation_timeout, propagation_limit, propagation_delay, propagation_concurrency, propagation_batch_size

Object TTL

# Create with timestamp-based TTL (requires inverted_index timestamp for existing collections)
weaviate-cli create collection --collection MyTTL --inverted_index timestamp --object_ttl_type create --object_ttl_time 3600 --json

# Create with property-based TTL (date property, time=0 means expire at exact property date)
weaviate-cli create collection --collection MyTTL --object_ttl_type property --object_ttl_time 0 --object_ttl_property_name expiresAt --json

# Enable TTL on existing collection
weaviate-cli update collection --collection MyTTL --object_ttl_type create --object_ttl_time 3600 --object_ttl_filter_expired true --json

# Disable TTL (use "disable", not "disabled")
weaviate-cli update collection --collection MyTTL --object_ttl_type disable --json

TTL types: create (by _creationTimeUnix), update (by _lastUpdateTimeUnix), property (by custom date property), disable

Note: --object_ttl_time is in seconds. Value of 0 is valid for property type (expire at exact date). Timestamp types (create/update) require a minimum of 60 seconds.

See references/collections.md for full options.

Data

weaviate-cli create data --collection Movies --limit 1000 --randomize --json
weaviate-cli query data --collection Movies --search_type hybrid --query "Action movie" --limit 10 --json
weaviate-cli update data --collection Movies --limit 100 --randomize --json
weaviate-cli delete data --collection Movies --limit 100 --json
weaviate-cli delete data --collection Movies --uuid "abc-123" --json

Search types: fetch, vector (near_text), keyword (bm25), hybrid, uuid

Key data options: --consistency_level, --auto_tenants N, --tenants "T1,T2", --vector_dimensions, --batch_size, --concurrent_requests, --wait_for_indexing, --dynamic_batch, --multi_vector

Key query options: --properties "title,keywords", --tenants "T1", --target_vector "default", --consistency_level

Note: --consistency_level values must be lowercase: one, quorum, all (not ONE, QUORUM, ALL).

Alias support: The --collection flag accepts collection aliases in all data commands. If the name isn't a direct collection, the CLI checks the alias list automatically.

See references/data.md and references/search.md.

Tenants

weaviate-cli create tenants --collection Movies --number_tenants 100 --tenant_suffix "Tenant" --state active --json
weaviate-cli create tenants --collection Movies --tenants "Alice,Bob,Charlie" --state active --json
weaviate-cli get tenants --collection Movies --json
weaviate-cli get tenants --collection Movies --tenant_id "Tenant-1" --verbose --json
weaviate-cli update tenants --collection Movies --state cold --number_tenants 100 --json
weaviate-cli update tenants --collection Movies --state hot --tenants "Tenant-1,Tenant-2" --json
weaviate-cli delete tenants --collection Movies --number_tenants 100 --json
weaviate-cli delete tenants --collection Movies --tenants "Tenant-1,Tenant-2" --json

States: hot/active, cold/inactive, frozen/offloaded

See references/tenants.md.

Backups

weaviate-cli create backup --backend s3 --backup_id my-backup --wait --json
weaviate-cli create backup --backend s3 --backup_id my-backup --include "Movies,Books" --wait --json
weaviate-cli create backup --backend s3 --backup_id my-incremental --incremental_base_backup_id my-backup --json
weaviate-cli get backup --backend s3 --backup_id my-backup --json
weaviate-cli get backup --backend s3 --backup_id my-backup --restore --json
weaviate-cli restore backup --backend s3 --backup_id my-backup --wait --json
weaviate-cli cancel backup --backend s3 --backup_id my-backup --json

Backends: s3, gcs, filesystem. Options: --include, --exclude, --wait, --cpu_for_backup N, --override-alias, --incremental_base_backup_id

See references/backups.md.

Collection Export

weaviate-cli create export-collection --export_id my-export --backend s3 --file_format parquet --wait --json
weaviate-cli create export-collection --export_id my-export --backend s3 --include "Movies,Books" --json
weaviate-cli create export-collection --export_id my-export --backend s3 --exclude "TempData" --json
weaviate-cli get export-collection --export_id my-export --backend s3 --json
weaviate-cli cancel export-collection --export_id my-export --backend s3 --json

Backends: filesystem, s3, gcs, azure. File formats: parquet.

Options: --include, --exclude (mutually exclusive), --wait

Prerequisite: The export backend must be configured on the Weaviate cluster (e.g., COLLECTION_EXPORT=true in local-k8s, which provisions MinIO and the weaviate-export bucket automatically).

See references/exports.md.

RBAC (Roles, Users, Permissions)

weaviate-cli create role --role_name MoviesAdmin -p crud_collections:Movies -p crud_data:Movies --json
weaviate-cli create user --user_name test-user --json
weaviate-cli create user --user_name test-user --store --json  # Store API key in config
weaviate-cli assign role --role_name MoviesAdmin --user_name test-user --json
weaviate-cli assign role --role_name MoviesAdmin --role_name TenantAdmin --user_name test-user --json  # Multiple roles
weaviate-cli assign permission -p read_data:Movies --role_name MoviesAdmin --json
weaviate-cli get role --all --json
weaviate-cli get role --role_name MoviesAdmin --json
weaviate-cli get role --user_name test-user --json
weaviate-cli get user --all --json
weaviate-cli get user --user_name test-user --json
weaviate-cli get user --role_name MoviesAdmin --json
weaviate-cli update user --user_name test-user --rotate_api_key --json
weaviate-cli update user --user_name test-user --activate --json
weaviate-cli update user --user_name test-user --deactivate --json
weaviate-cli revoke role --role_name MoviesAdmin --user_name test-user --json
weaviate-cli revoke role --role_name MoviesAdmin --user_name oidc-user --user_type oidc --json  # OIDC user
weaviate-cli revoke permission -p read_data:Movies --role_name MoviesAdmin --json
weaviate-cli delete role --role_name MoviesAdmin --json
weaviate-cli delete user --user_name test-user --json

Permission format: action:target. See references/rbac.md for full permission reference.

Shell quoting: Permissions with wildcards must be quoted to prevent shell globbing: -p 'crud_data:*' (not -p crud_data:*, which fails in zsh with no matches found).

Cluster & Nodes

weaviate-cli get nodes --json                          # Default view
weaviate-cli get nodes --minimal --json                # Minimal (fast for large clusters)
weaviate-cli get nodes --shards --json                 # Per-shard details
weaviate-cli get nodes --collections --json            # Per-collection details
weaviate-cli get nodes --collection Movies --json      # Specific collection
weaviate-cli get shards --json                         # All collections
weaviate-cli get shards --collection Movies --json     # Specific collection
weaviate-cli update shards --collection Movies --status READY --json
weaviate-cli update shards --all --status READY --json
weaviate-cli query sharding-state Movies --json

Replication

weaviate-cli create replication --collection Movies --shard shard-1 --source-node node-1 --target-node node-2 --type COPY --json
weaviate-cli get replication <UUID> --json
weaviate-cli get replication <UUID> --history --json
weaviate-cli get all-replications --json
weaviate-cli query replications --collection Movies --json
weaviate-cli query replications --collection Movies --shard shard-1 --json
weaviate-cli query replications --target-node node-2 --json
weaviate-cli query replications --collection Movies --history --json  # Include history
weaviate-cli cancel replication <UUID> --json
weaviate-cli delete replication <UUID> --json
weaviate-cli delete all-replications --json

Types: COPY (duplicate shard), MOVE (migrate shard)

See references/cluster.md.

Aliases

weaviate-cli create alias MyAlias Movies --json
weaviate-cli get alias --alias_name MyAlias --json
weaviate-cli get alias --collection Movies --json
weaviate-cli get alias --all --json
weaviate-cli update alias MyAlias Movies_v2 --json
weaviate-cli delete alias MyAlias --json

Benchmark

weaviate-cli benchmark qps --collection Movies --query-type hybrid --max-duration 300 --json
weaviate-cli benchmark qps --collection Movies --qps 100 --json              # Fixed QPS
weaviate-cli benchmark qps --collection Movies --tenant "Tenant-0" --json    # Multi-tenant
weaviate-cli benchmark qps --collection Movies --output csv --generate-graph --file-alias staging --json

Key options: --query-type (hybrid/bm25/near_text), --qps N, --max-duration, --test-duration, --warmup-duration, --limit, --consistency-level, --latency-threshold, --concurrency, --query-terms

See references/benchmark.md.

Workflow Dependencies

Collection Lifecycle

1. create collection -- must exist before any operations on it
2. create tenants -- only if collection has --multitenant (or use --auto_tenant_creation)
3. create data -- collection must exist; for MT collections, tenants must exist or auto-creation enabled
4. query data -- collection must have data
5. delete data -> delete tenants -> delete collection (reverse order)

Multi-Tenancy State Machine

hot/active  <-->  cold/inactive
    ^   \              ^
    |    \             |
    v     v            v
      frozen/offloaded

• hot/active: data in memory, queryable, accepts writes
• cold/inactive: data on disk, not queryable
• frozen/offloaded: data in cloud storage, not queryable
• Tenants can be offloaded directly from hot/active or from cold/inactive
• Data operations require tenants in hot/active state

RBAC Workflow

1. create role --role_name X -p '<permission>' -- create role with permissions (quote wildcards!)
2. create user --user_name Y --store -- create user and auto-save API key into active config
3. assign role --role_name X --user_name Y -- assign role to user
4. Verify: get role --role_name X and get user --user_name Y
5. Test as new user: weaviate-cli --config-file <config> --user Y <command> --json
6. Cleanup: revoke role -> delete role / delete user

Prerequisite: The Weaviate cluster must be deployed with DYNAMIC_USERS=true for create user to work. Without it, only static API key users (configured at deploy time) are available.

Backup Workflow

1. create backup --backend s3 --backup_id my-backup --wait -- wait for completion
2. get backup --backend s3 --backup_id my-backup -- check status
3. restore backup --backend s3 --backup_id my-backup --wait -- restore
4. cancel backup -- cancel in-progress backup

Replication Workflow

1. get nodes -- identify source and target nodes
2. get shards --collection X -- identify shard to replicate
3. create replication --collection X --shard S --source-node A --target-node B --type COPY
4. get replication <UUID> -- monitor progress
5. cancel replication <UUID> -- cancel if needed
6. delete replication <UUID> -- cleanup completed operation

Object TTL Workflow

1. create collection --object_ttl_type create --object_ttl_time 3600 -- create with TTL (or update collection to enable later)
2. TTL requires server-side objects_ttl_delete_schedule runtime config to be set (e.g., @every 10s)
3. get collection --collection X -- verify objectTtlConfig in response
4. update collection --object_ttl_type disable -- disable TTL (stops background deletion)
5. For timestamp-based TTL on existing collections: --inverted_index timestamp must be set at creation or already enabled
6. For property-based TTL: the date property must exist, be date type, and have filterable or rangeable index

Collection Export Workflow

1. create export-collection --backend s3 --export_id my-export --wait -- create and wait for completion
2. get export-collection --backend s3 --export_id my-export -- check status (includes shard-level progress)
3. cancel export-collection --backend s3 --export_id my-export -- cancel in-progress export

Prerequisite: The export backend must be configured on the cluster. For local-k8s, deploy with COLLECTION_EXPORT=true, which provisions MinIO, creates the weaviate-export bucket, and wires EXPORT_DEFAULT_BUCKET automatically.

Alias Workflow

1. create collection --collection Movies_v1 -- create the target collection
2. create alias Movies Movies_v1 -- create alias pointing to collection
3. update alias Movies Movies_v2 -- repoint alias to new collection
4. get alias --alias_name Movies -- inspect alias
5. delete alias Movies -- remove alias

JSON Output

All commands support --json for machine-readable output. Always use --json when invoking commands programmatically.

Success responses return structured data or:

{"status": "success", "message": "..."}

Error responses are printed to stderr and the process exits with code 1:

Error: <description>

Error Handling

Error	Cause	Solution
Config file does not exist	Missing config	Create config or use --config-file
User must be specified when auth type is 'user'	Missing --user flag	Add --user <name>
User 'X' not found in config file	User not in config auth section	Add user to config or check spelling
GRPC connection seems to be unavailable	gRPC port blocked	Check firewall/network; CLI retries skipping checks
Error: Collection 'X' does not exist	Collection not created yet	Run create collection first

Environment Variables

Variable	Description
SLOW_CONNECTION	Set to 1/true to double all client timeouts
HOME	Used to locate default config at ~/.config/weaviate/config.json

Maintaining This Skill

When new commands or options are added to weaviate-cli:

1. Update the Command Reference section above with the new command syntax
2. Update or create the relevant reference file in references/
3. If a new command group is added, update the Command Groups table
4. Ensure all examples include --json
5. Update workflow dependency sections if the new command introduces dependencies

References

• references/collections.md -- Full collection options and notes
• references/data.md -- Data ingestion options and notes
• references/search.md -- Search types, options, and selection guide
• references/tenants.md -- Tenant state machine and management
• references/backups.md -- Backup/restore options and notes
• references/exports.md -- Collection export options and notes
• references/rbac.md -- Permission format, actions, and examples
• references/cluster.md -- Nodes, shards, replication operations
• references/benchmark.md -- Benchmark options and output modes
• references/config-management.md -- Config patterns and decision tree