zilliz-cloud（齐利兹云）

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

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

python3 -m pip install --upgrade zilliz-cli

Verify installation:

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:

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

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

zilliz login --api-key

Option 2b: API Key via configure (legacy)

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):

export ZILLIZ_API_KEY=<your-api-key>

After the user completes authentication, verify by running:

zilliz auth status

Configure Subcommands

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:

# Interactive selection
zilliz auth switch

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

Logout

zilliz logout

Set Cluster Context

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

# 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

zilliz context current

Output Format

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

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

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

Cluster Type Differences

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

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

Describe a Cluster

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

Create a Cluster

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

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

Delete / Suspend / Resume a Cluster

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

Modify a Cluster

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

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

Create a Collection

Quick create with auto schema:

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:

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

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

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

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

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

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)

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

Get by ID

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

Insert / Upsert Vectors

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:

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

Delete Vectors

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

Filter Expression Syntax

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

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

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

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

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

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

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

# 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

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

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

Restore to a New Cluster

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

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

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

# 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

# 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

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

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: \<name\> (\<cluster-id\>) Status: RUNNING | Region: \<region\> | Plan: \<plan\> Database: \<current-db\>

Collections:

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.