Zilliz Cloud CLI Skill#

Your Zilliz Cloud console in the terminal. This skill enables you to operate the zilliz-cli, bringing the full power of Zilliz Cloud — cluster management, collection operations, vector search, RBAC, backups, and more — through natural language.

When to Use#

Use this skill when the user wants to:

• Manage Zilliz Cloud clusters (create, delete, suspend, resume, modify)
• Work with Milvus collections (create, describe, load, release, drop)
• Perform vector operations (search, query, insert, upsert, delete)
• Manage indexes, databases, partitions
• Set up users, roles, and access control (RBAC)
• Create and manage backups or backup policies
• Import bulk data from cloud storage
• Check billing, usage, or invoices
• Monitor cluster and collection status

Capabilities Overview#

AreaWhat You Can DoClustersCreate, delete, suspend, resume, modifyCollectionsCreate with custom schema, load, release, rename, dropVectorsSearch, query, insert, upsert, deleteIndexesCreate, list, describe, dropDatabasesCreate, list, describe, dropUsers & RolesRBAC setup, privilege managementBackupsCreate, restore, export, policy managementImportBulk data import from cloud storagePartitionsCreate, load, release, manageMonitoringCluster status, collection statsBillingUsage, invoices, payment methodsProjectsProject and region management

Requirements#

• Python 3.10+
• A Zilliz Cloud account (or local Milvus instance)

---

Setup & Authentication#

Prerequisites#

Before running any zilliz-cli command, verify the following in order:

1. CLI installed and up to date? Run python3 -m pip install --upgrade zilliz-cli to ensure the latest version is installed.
2. Logged in? Run zilliz auth status. If not logged in, guide through login (see below).
3. Context set? (Only for data-plane operations) Run zilliz context current. If no context, guide through context setup.

Install / Upgrade CLI#

bash

python3 -m pip install --upgrade zilliz-cli

Verify installation:

bash

zilliz --version

Authentication#

IMPORTANT: Login commands ( zilliz login, zilliz configure) require an interactive terminal and CANNOT run inside the AI agent. Always instruct the user to run these in their own terminal.

Check if already logged in:

bash

zilliz auth status

If not logged in, tell the user to open their own terminal and run one of the following:

Option 1: Browser-based login (OAuth) — full feature access

text

zilliz login

• Opens a browser for authentication
• Retrieves user info, organization data, and API keys
• Use --no-browser in headless environments (displays a URL to visit manually)

Option 2a: API Key via login command

text

zilliz login --api-key

Option 2b: API Key via configure (legacy)

text

zilliz configure

• Prompts for an API key (found in Zilliz Cloud console under API Keys)
• Limitations compared to OAuth login:
  • Organization switching not available
  • On Serverless clusters: database management, user/role management may be restricted
  • Some control-plane operations may require OAuth login

Option 3: Environment variable

User can add to their shell profile ( .zshrc / .bashrc):

text

export ZILLIZ_API_KEY=<your-api-key>

After the user completes authentication, verify by running:

bash

zilliz auth status

Configure Subcommands#

bash

zilliz configure              # Interactive API key setup
zilliz configure list          # Show all config values
zilliz configure set <key> <value>  # Set a config value
zilliz configure get <key>     # Get a config value
zilliz configure clear         # Clear all credentials

Switch Organization#

These commands require an interactive terminal. Instruct the user to run in their own terminal:

text

# Interactive selection
zilliz auth switch

# Direct switch by org ID
zilliz auth switch <org-id>

Logout#

bash

zilliz logout

Set Cluster Context#

Data-plane commands (collection, vector, index, etc.) require an active cluster context.

bash

# Set by cluster ID (endpoint auto-resolved)
zilliz context set --cluster-id <cluster-id>

# Set with explicit endpoint
zilliz context set --cluster-id <cluster-id> --endpoint <url>

# Change database (default: "default")
zilliz context set --database <db-name>

View Current Context#

bash

zilliz context current

Output Format#

All zilliz-cli commands support --output json for structured, machine-readable output:

bash

zilliz cluster list --output json
zilliz collection describe --name <name> --output json

Available formats: json, table, text. Default is text.

Cluster Type Differences#

FeatureFreeServerlessDedicatedCollection CRUDYesYesYesVector search/queryYesYesYesDatabase create/dropNoNoYesUser/role managementNoLimitedYesBackup managementNoYesYesCluster modifyNoNoYes

---

Quickstart Command#

Guide the user through the complete Zilliz Cloud CLI setup:

1. Check Python — python3 --version (need 3.10+)
2. Install CLI — python3 -m pip install --upgrade zilliz-cli then zilliz --version
3. Authenticate — zilliz auth status; if not logged in, instruct user to run zilliz login in their own terminal
4. List clusters — zilliz cluster list; if none, offer to create one
5. Set context — zilliz context set --cluster-id <id>
6. Verify — zilliz context current and zilliz collection list

---

Cluster Management#

List Clusters#

bash

zilliz cluster list
zilliz cluster list --page-size 10 --page 1
zilliz cluster list --all

Describe a Cluster#

bash

zilliz cluster describe --cluster-id <cluster-id>

Create a Cluster#

bash

# Serverless (default)
zilliz cluster create --type serverless --name <name> --project-id <project-id> --region <region-id>

# Free tier
zilliz cluster create --type free --name <name> --project-id <project-id> --region <region-id>

# Dedicated
zilliz cluster create --type dedicated \
  --name <name> \
  --project-id <project-id> \
  --region <region-id> \
  --cu-type <cu-type> \
  --cu-size <cu-size>

To find available project IDs, cloud providers, and regions:

bash

zilliz project list
zilliz cluster providers
zilliz cluster regions
zilliz cluster regions --cloud-id <cloud-id>

Delete / Suspend / Resume a Cluster#

bash

zilliz cluster delete --cluster-id <cluster-id>
zilliz cluster suspend --cluster-id <cluster-id>
zilliz cluster resume --cluster-id <cluster-id>

Modify a Cluster#

bash

zilliz cluster modify --cluster-id <cluster-id> --cu-size <new-size>
zilliz cluster modify --cluster-id <cluster-id> --replica <count>
zilliz cluster modify --cluster-id <cluster-id> --body '{"cuSize": 2, "replica": 2}'

Cluster Guidance#

• Before creating a cluster, help the user choose a region by running zilliz cluster providers and zilliz cluster regions.
• Cluster creation is asynchronous. After cluster create, poll with zilliz cluster describe until status becomes RUNNING.
• Before deleting a cluster, always confirm with the user — this is irreversible.
• After creating a cluster, suggest setting context with zilliz context set --cluster-id <id>.

---

Collection Management#

All collection commands accept an optional --database <db-name> flag.

List / Describe Collections#

bash

zilliz collection list
zilliz collection list --database <db-name>
zilliz collection describe --name <collection-name>

Create a Collection#

Quick create with auto schema:

bash

zilliz collection create --name <name> --dimension <dim>
# Optional: --metric-type COSINE|L2|IP --id-type Int64|VarChar --auto-id true|false

Advanced create with custom schema:

bash

zilliz collection create --name <name> --body '{
  "schema": {
    "fields": [
      {"fieldName": "id", "dataType": "Int64", "isPrimary": true},
      {"fieldName": "vector", "dataType": "FloatVector", "elementTypeParams": {"dim": "768"}},
      {"fieldName": "text", "dataType": "VarChar", "elementTypeParams": {"max_length": "1024"}}
    ]
  }
}'

Drop / Rename / Check Existence#

bash

zilliz collection drop --name <collection-name>
zilliz collection rename --name <old-name> --new-name <new-name>
zilliz collection rename --name <old-name> --new-name <new-name> --new-database <db-name>
zilliz collection has --name <collection-name>

Load / Release / Stats#

bash

zilliz collection load --name <collection-name>
zilliz collection release --name <collection-name>
zilliz collection get-stats --name <collection-name>
zilliz collection get-load-state --name <collection-name>
zilliz collection flush --name <collection-name>
zilliz collection compact --name <collection-name>

Collection Aliases#

bash

zilliz alias create --collection <collection-name> --alias <alias-name>
zilliz alias list --database <db-name>
zilliz alias list --database <db-name> --collection <collection-name>
zilliz alias describe --alias <alias-name>
zilliz alias alter --collection <new-collection-name> --alias <alias-name>
zilliz alias drop --alias <alias-name>

Collection Guidance#

• Ask about use case to recommend dimension, metric type, and schema.
• Before dropping a collection, confirm with the user — this deletes all data.
• A collection must be loaded before search or query.
• Use describe to inspect schema before vector operations.

---

Vector Operations#

All vector commands accept an optional --database <db-name> flag. Target collection must exist and be loaded.

Vector Search#

bash

zilliz vector search \
  --collection <collection-name> \
  --data '[[0.1, 0.2, 0.3, ...]]' \
  --limit 10
# Optional:
#   --filter 'age > 20 and status == "active"'
#   --output-fields '["field1", "field2"]'
#   --anns-field <vector-field-name>

Hybrid Search#

bash

zilliz vector hybrid-search \
  --collection <collection-name> \
  --search '[
    {"data": [[0.1, 0.2, ...]], "annsField": "dense_vector", "limit": 10},
    {"data": [["search text"]], "annsField": "sparse_vector", "limit": 10}
  ]' \
  --rerank '{"strategy": "rrf", "params": {"k": 60}}' \
  --limit 10
# Optional: --output-fields '["field1", "field2"]'

Query (Filter-Based Retrieval)#

bash

zilliz vector query \
  --collection <collection-name> \
  --filter 'id in [1, 2, 3]' \
  --limit 10
# Optional: --output-fields '["field1", "field2"]'

Get by ID#

bash

zilliz vector get \
  --collection <collection-name> \
  --id '[1, 2, 3]'
# Optional: --output-fields '["field1", "field2"]'

Insert / Upsert Vectors#

bash

zilliz vector insert \
  --collection <collection-name> \
  --data '[
    {"id": 1, "vector": [0.1, 0.2, ...], "text": "hello"},
    {"id": 2, "vector": [0.3, 0.4, ...], "text": "world"}
  ]'

zilliz vector upsert \
  --collection <collection-name> \
  --data '[{"id": 1, "vector": [0.1, ...], "text": "updated"}]'
# Optional: --partition <partition-name>

For large datasets, read from file:

bash

zilliz vector insert --collection <name> --data "$(cat data.json)"

Delete Vectors#

bash

zilliz vector delete \
  --collection <collection-name> \
  --filter 'id in [1, 2, 3]'
# Optional: --partition <partition-name>

Filter Expression Syntax#

ExpressionExampleComparisonage > 20Equalitystatus == "active"IN listid in [1, 2, 3]AND/ORage > 20 and status == "active"String matchtext like "hello%"Array containstags array_contains "ml"

Vector Guidance#

• Before searching, inspect schema with zilliz collection describe for field names and dimensions.
• The --data value must match the collection's vector dimension exactly.
• For text-to-vector search, the user needs an embedding model to convert text to vectors first.
• For large insert operations, suggest writing data to a JSON file first.

---

Index Management#

All index commands accept an optional --database <db-name> flag.

Create an Index#

bash

zilliz index create --collection <collection-name> --body '{
  "indexParams": [
    {
      "fieldName": "vector",
      "indexName": "vector_index",
      "metricType": "COSINE",
      "indexType": "AUTOINDEX"
    }
  ]
}'

Common index types: AUTOINDEX (recommended), IVF_FLAT, IVF_SQ8, HNSW. Common metric types: COSINE, L2, IP.

List / Describe / Drop Indexes#

bash

zilliz index list --collection <collection-name>
zilliz index describe --collection <collection-name> --index-name <index-name>
zilliz index drop --collection <collection-name> --index-name <index-name>

Index Guidance#

• On Zilliz Cloud, AUTOINDEX is recommended for most use cases.
• An index is required before loading a collection for search.
• After creating an index, remind the user to load the collection.

---

Database Management#

Commands#

bash

zilliz database list
zilliz database create --name <db-name>
zilliz database create --name <db-name> --body '{"properties": {}}'
zilliz database describe --name <db-name>
zilliz database drop --name <db-name>

Database Guidance#

• Database create, describe, and drop are only available on Dedicated clusters. database list works on all cluster types.
• Every cluster has a "default" database.
• Before dropping a database, confirm with the user — all collections in it will be deleted.
• After creating a database, suggest switching context: zilliz context set --database <db-name>.

---

Partition Management#

Commands#

bash

zilliz partition list --collection <collection-name>
zilliz partition create --collection <collection-name> --partition <partition-name>
zilliz partition has --collection <collection-name> --partition <partition-name>
zilliz partition get-stats --collection <collection-name> --partition <partition-name>
zilliz partition load --collection <collection-name> --names '["partition1", "partition2"]'
zilliz partition release --collection <collection-name> --names '["partition1", "partition2"]'
zilliz partition drop --collection <collection-name> --partition <partition-name>

Partition Guidance#

• Every collection has a default _default partition.
• A partition must be loaded before it can be searched.
• Before dropping a partition, confirm with the user.

---

User & Role Management (RBAC)#

Only available on Dedicated clusters.

Users#

bash

zilliz user list
zilliz user create --user <username> --password <password>
zilliz user describe --user <username>
zilliz user update-password --user <username> --password <old-password> --new-password <new-password>
zilliz user grant-role --user <username> --role <role-name>
zilliz user revoke-role --user <username> --role <role-name>
zilliz user drop --user <username>

Roles#

bash

zilliz role list
zilliz role create --role <role-name>
zilliz role describe --role <role-name>
zilliz role grant-privilege \
  --role <role-name> \
  --object-type <Collection|Global|Database> \
  --object-name <name-or-*> \
  --privilege <privilege-name>
zilliz role revoke-privilege \
  --role <role-name> \
  --object-type <Collection|Global|Database> \
  --object-name <name-or-*> \
  --privilege <privilege-name>
zilliz role drop --role <role-name>

Common privileges:

• Collection: Search, Query, Insert, Delete, CreateIndex, DropCollection
• Global: CreateCollection, All
• Database: ListCollections

RBAC Guidance#

• Built-in roles: admin (full access), public (no privileges by default).
• Suggested workflow: create role → grant privileges → create user → assign role.
• Use * as object-name to grant privilege on all objects of that type.

---

Backup Management#

No cluster context required — backup operations use --cluster-id directly.

Create a Backup#

bash

# Full cluster backup
zilliz backup create --cluster-id in01-xxxxxxxxxxxx

# Collection-level backup
zilliz backup create --cluster-id in01-xxxxxxxxxxxx --database default --collection my_col

List / Describe / Delete Backups#

bash

zilliz backup list
zilliz backup list --cluster-id <cluster-id>
zilliz backup list --creation-method manual   # or: auto
zilliz backup list --backup-type CLUSTER      # or: COLLECTION
zilliz backup describe --cluster-id <cluster-id> --backup-id <backup-id>
zilliz backup delete --cluster-id <cluster-id> --backup-id <backup-id>

Export a Backup#

bash

zilliz backup export \
  --cluster-id <cluster-id> \
  --backup-id <backup-id> \
  --integration-id <integration-id> \
  --directory <path>

Restore to a New Cluster#

bash

zilliz backup restore-cluster \
  --cluster-id <source-cluster-id> \
  --backup-id <backup-id> \
  --project-id <project-id> \
  --name <new-cluster-name> \
  --cu-size <size> \
  --collection-status LOADED

Restore Specific Collections#

bash

zilliz backup restore-collection \
  --cluster-id <source-cluster-id> \
  --backup-id <backup-id> \
  --dest-cluster-id <destination-cluster-id> \
  --body '{"collections": [{"source": "col1", "target": "col1_restored"}]}'

Backup Policy#

bash

zilliz backup describe-policy --cluster-id <cluster-id>

# Enable daily backup
zilliz backup update-policy --cluster-id in01-xxxx --auto-backup true --frequency daily --start-time 02:00 --retention-days 7

# Enable backup on Mon/Wed/Fri
zilliz backup update-policy --cluster-id in01-xxxx --auto-backup true --frequency 1,3,5 --start-time 03:00-05:00 --retention-days 14

# Disable auto-backup
zilliz backup update-policy --cluster-id in01-xxxx --auto-backup false

Backup Guidance#

• Before deleting a backup, confirm with the user — this is irreversible.
• Explain difference: cluster restore = new cluster, collection restore = into existing cluster.
• Suggest backup policies for production clusters.

---

Data Import#

Target collection must exist on the target cluster.

Commands#

bash

# Start import job
zilliz import start \
  --cluster-id <cluster-id> \
  --collection <collection-name> \
  --body '{
    "files": [["s3://bucket/path/to/file.parquet"]],
    "options": {}
  }'

# List import jobs
zilliz import list --cluster-id <cluster-id>
zilliz import list --cluster-id <cluster-id> --database <db-name>

# Check import status
zilliz import status --cluster-id <cluster-id> --job-id <job-id>

Supported file formats: Parquet, JSON, CSV.

Import Guidance#

• Import jobs run asynchronously — use import status to track progress.
• Data files must be accessible from Zilliz Cloud (e.g., S3, GCS with integration configured).
• Collection schema must match the data file structure.

---

Billing#

Requires OAuth login (not API Key mode).

Commands#

bash

# Usage
zilliz billing usage --last 7d
zilliz billing usage --month this
zilliz billing usage --month last
zilliz billing usage --month 2026-01
zilliz billing usage --start 2026-01-01 --end 2026-01-31

# Invoices
zilliz billing invoices
zilliz billing invoices --all
zilliz billing invoices --invoice-id inv-xxxxxxxxxxxx

# Bind credit card (instruct user to run in their own terminal)
zilliz billing bind-card --card-number <number> --exp-month <1-12> --exp-year <year> --cvc <code>

Billing Guidance#

• The bind-card command handles sensitive card data — always instruct the user to run it in their own terminal.

---

Project & Region Management#

Projects#

bash

zilliz project list
zilliz project describe --project-id <project-id>
zilliz project create --name <project-name> --plan <Free|Serverless|Standard|Enterprise>
zilliz project upgrade --project-id <project-id> --plan <Serverless|Standard|Enterprise>

Volumes#

bash

zilliz volume create --project-id <project-id> --region <region-id> --name <volume-name>
zilliz volume list --project-id <project-id>
zilliz volume delete --name <volume-name>

---

Monitoring & Status#

Status Overview Workflow#

When the user asks for status, gather and present:

1. zilliz context current --output json
2. zilliz cluster describe --cluster-id <id> --output json
3. zilliz database list --output json
4. zilliz collection list --output json
5. For each collection: zilliz collection get-stats --name <name> --output json and zilliz collection get-load-state --name <name> --output json

Present as:

Cluster: () Status: RUNNING | Region: | Plan: Database:

Collections:

CollectionRowsLoad Statemy_collection10,000Loaded

---

General Guidance#

• Always check prerequisites (CLI installed, logged in, context set) before executing commands.
• NEVER run zilliz login, zilliz configure, or zilliz auth switch inside the AI agent — they require interactive input.
• NEVER ask the user to paste API keys into the chat — guide them to configure credentials in their own terminal.
• Before any destructive operation (delete cluster, drop collection, drop database, delete backup), always confirm with the user.
• Use --output json when parsing results programmatically, then format into readable summaries.
• When a command fails with permissions error, check the cluster type first.
• When a command fails unexpectedly, consider whether the cluster type or auth mode may be the cause.