Zilliz Cloud

SKILL.md

---
name: "zilliz-cloud"
version: "0.3.0"
description: "Manage Zilliz Cloud clusters and Milvus vector databases — cluster ops, collections, vector search, RBAC, backups, imports, and more via zilliz-cli."
tags: ["zilliz", "milvus", "vector-database", "semantic-search", "rag", "cloud", "database"]
metadata:
  openclaw:
    emoji: "\U0001F50D"
    homepage: "https://github.com/zilliztech/zilliz-plugin"
    primaryEnv: "ZILLIZ_API_KEY"
    requires:
      env:
        - ZILLIZ_API_KEY
      bins:
        - python3
        - zilliz
      os:
        - darwin
        - linux
    install:
      - kind: uv
        package: zilliz-cli
        bins:
          - zilliz
---

# 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](https://zilliz.com/) — 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

| Area | What You Can Do |
|------|----------------|
| **Clusters** | Create, delete, suspend, resume, modify |
| **Collections** | Create with custom schema, load, release, rename, drop |
| **Vectors** | Search, query, insert, upsert, delete |
| **Indexes** | Create, list, describe, drop |
| **Databases** | Create, list, describe, drop |
| **Users & Roles** | RBAC setup, privilege management |
| **Backups** | Create, restore, export, policy management |
| **Import** | Bulk data import from cloud storage |
| **Partitions** | Create, load, release, manage |
| **Monitoring** | Cluster status, collection stats |
| **Billing** | Usage, invoices, payment methods |
| **Projects** | Project and region management |

## Requirements

- Python 3.10+
- A [Zilliz Cloud](https://cloud.zilliz.com/) 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**

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

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

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

| Feature | Free | Serverless | Dedicated |
|---|---|---|---|
| Collection CRUD | Yes | Yes | Yes |
| Vector search/query | Yes | Yes | Yes |
| Database create/drop | No | No | Yes |
| User/role management | No | Limited | Yes |
| Backup management | No | Yes | Yes |
| Cluster modify | No | No | Yes |

---

# 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

| Expression | Example |
|---|---|
| Comparison | `age > 20` |
| Equality | `status == "active"` |
| IN list | `id in [1, 2, 3]` |
| AND/OR | `age > 20 and status == "active"` |
| String match | `text like "hello%"` |
| Array contains | `tags 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:** \<name\> (\<cluster-id\>)
**Status:** RUNNING | **Region:** \<region\> | **Plan:** \<plan\>
**Database:** \<current-db\>

**Collections:**

| Collection | Rows | Load State |
|---|---|---|
| my_collection | 10,000 | Loaded |

---

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