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.jsonwithout 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 frequency=60 \
--async_replication_config hashtree_height=16 \
--async_replication_config propagation_concurrency=4 --json
# Update async replication config on existing collection
weaviate-cli update collection --collection MyCol \
--async_replication_config propagation_delay=30 \
--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
Deprecated (removed from the server schema in Weaviate v1.37.3 and silently ignored from that version on, but still accepted for older servers): max_workers, alive_nodes_checking_frequency.
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
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
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).
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)
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
Workflow Dependencies
Collection Lifecycle
create collection-- must exist before any operations on itcreate tenants-- only if collection has--multitenant(or use--auto_tenant_creation)create data-- collection must exist; for MT collections, tenants must exist or auto-creation enabledquery data-- collection must have datadelete 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 writescold/inactive: data on disk, not queryablefrozen/offloaded: data in cloud storage, not queryable- Tenants can be offloaded directly from
hot/activeor fromcold/inactive - Data operations require tenants in
hot/activestate
RBAC Workflow
create role --role_name X -p '<permission>'-- create role with permissions (quote wildcards!)create user --user_name Y --store-- create user and auto-save API key into active configassign role --role_name X --user_name Y-- assign role to user- Verify:
get role --role_name Xandget user --user_name Y - Test as new user:
weaviate-cli --config-file <config> --user Y <command> --json - 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
create backup --backend s3 --backup_id my-backup --wait-- wait for completionget backup --backend s3 --backup_id my-backup-- check statusrestore backup --backend s3 --backup_id my-backup --wait-- restorecancel backup-- cancel in-progress backup
Replication Workflow
get nodes-- identify source and target nodesget shards --collection X-- identify shard to replicatecreate replication --collection X --shard S --source-node A --target-node B --type COPYget replication <UUID>-- monitor progresscancel replication <UUID>-- cancel if neededdelete replication <UUID>-- cleanup completed operation
Object TTL Workflow
create collection --object_ttl_type create --object_ttl_time 3600-- create with TTL (orupdate collectionto enable later)- TTL requires server-side
objects_ttl_delete_scheduleruntime config to be set (e.g.,@every 10s) get collection --collection X-- verifyobjectTtlConfigin responseupdate collection --object_ttl_type disable-- disable TTL (stops background deletion)- For timestamp-based TTL on existing collections:
--inverted_index timestampmust be set at creation or already enabled - For property-based TTL: the date property must exist, be
datetype, and have filterable or rangeable index
Collection Export Workflow
create export-collection --backend s3 --export_id my-export --wait-- create and wait for completionget export-collection --backend s3 --export_id my-export-- check status (includes shard-level progress)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
create collection --collection Movies_v1-- create the target collectioncreate alias Movies Movies_v1-- create alias pointing to collectionupdate alias Movies Movies_v2-- repoint alias to new collectionget alias --alias_name Movies-- inspect aliasdelete 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:
- Update the Command Reference section above with the new command syntax
- Update or create the relevant reference file in
references/ - If a new command group is added, update the Command Groups table
- Ensure all examples include
--json - 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