Skill: zhanshuyou/zilliz-skill (version 0.0.2)

--- name: zilliz description: > Manage Zilliz Cloud vector databases via zilliz-cli. Use when the user wants to: (1) set up zilliz-cli (install, login, configure), (2) manage clusters (create, list, describe, suspend, resume, delete, modify), (3) manage collections, indexes, partitions, databases, or aliases, (4) perform vector operations (search, query, insert, upsert, delete, hybrid search), (5) manage users, roles, and RBAC privileges, (6) handle backups, imports, billing, monitoring, projects, or regions. Triggers on: zilliz, vector database, semantic search, RAG, embeddings, collection schema, vector index, similarity search, zilliz-cli. --- # Zilliz Cloud CLI Skill Operate Zilliz Cloud through `zilliz-cli`. All operations are executed via shell commands. ## Prerequisite Check (always run first) Before any operation, verify in order: ```bash python3 -m pip show zilliz-cli # 1. CLI installed? If not: pip install --upgrade zilliz-cli zilliz auth status # 2. Logged in? If not: guide user to login in their terminal zilliz context current # 3. Context set? (only for data-plane ops) ``` **CRITICAL:** `zilliz login`, `zilliz configure`, and `zilliz auth switch` require interactive input — NEVER run them in a non-interactive shell. Instruct the user to run in their own terminal. NEVER ask for API keys in chat. ## Command Pattern ``` zilliz <resource> <action> --flag <value> [--optional-flag <value>] ``` All commands support `--output json|table|text` (default: `text`). Use `--output json` for programmatic parsing. ## Cluster Type Capabilities | Feature | Free | Serverless | Dedicated | |---|---|---|---| | Collection CRUD & Vector ops | Yes | Yes | Yes | | Database create/drop | No | No | Yes | | User/role management | No | Limited | Yes | | Backup management | No | Yes | Yes | | Cluster modify (CU/replica) | No | No | Yes | Check cluster type first when a command fails with permission errors. ## Reference Files Each reference covers one resource domain with full command syntax, options, and guidance. Read the relevant reference when handling that domain: | Domain | Reference | When to read | |---|---|---| | Setup & auth | [references/setup.md](references/setup.md) | Install, login, context, config, troubleshooting | | Clusters | [references/cluster.md](references/cluster.md) | Create, list, describe, modify, suspend, resume, delete clusters | | Collections | [references/collection.md](references/collection.md) | Create, list, describe, drop, rename, load, release, aliases | | Vectors | [references/vector.md](references/vector.md) | Search, query, insert, upsert, get, delete, hybrid search, filters | | Indexes | [references/index.md](references/index.md) | Create, list, describe, drop indexes | | Databases | [references/database.md](references/database.md) | Create, list, describe, drop databases | | Partitions | [references/partition.md](references/partition.md) | Create, list, load, release, drop partitions | | Users & roles | [references/user-role.md](references/user-role.md) | RBAC: users, roles, privileges (Dedicated only) | | Backups | [references/backup.md](references/backup.md) | Create, restore, export backups; manage backup policies | | Import | [references/import.md](references/import.md) | Bulk data import from cloud storage | | Billing | [references/billing.md](references/billing.md) | Usage queries, invoices, payment methods | | Monitoring | [references/monitoring.md](references/monitoring.md) | Cluster status, collection stats, load states | | Projects & regions | [references/project-region.md](references/project-region.md) | Projects, volumes, cloud providers, regions | ## Quick-Start Workflow For new users, guide through setup in order: 1. Install CLI: `python3 -m pip install --upgrade zilliz-cli` 2. Authenticate: user runs `zilliz login` in their terminal 3. Verify: `zilliz auth status` 4. List clusters: `zilliz cluster list` 5. Set context: `zilliz context set --cluster-id <id>` 6. Verify: `zilliz context current && zilliz collection list` ## Common Workflows **Create collection and prepare for search:** 1. `zilliz collection create --name <name> --dimension <dim>` — create 2. `zilliz index create --collection <name>` — index (AUTOINDEX recommended) 3. `zilliz collection load --name <name>` — load into memory 4. `zilliz vector search --collection <name> --data '[[...]]'` — search **Status overview** (read [references/monitoring.md](references/monitoring.md)): 1. `zilliz context current --output json` 2. `zilliz cluster describe --cluster-id <id> --output json` 3. `zilliz database list --output json` 4. For each DB: `collection list`, `get-stats`, `get-load-state`, `index list` 5. Present as formatted table ## Async Operations These return immediately; poll for completion: | Operation | Poll command | |---|---| | `cluster create` | `cluster describe --cluster-id <id>` until RUNNING | | `backup create/export/restore-*` | `backup describe --cluster-id <id> --backup-id <bid>` | | `import start` | `import status --job-id <jid> --cluster-id <id>` | ## Safety Rules - **Confirm before destructive ops:** drop collection/database, delete cluster/backup, drop user/role - **Sensitive commands in user's terminal:** `zilliz login`, `zilliz configure`, `zilliz billing bind-card` - **Never expose credentials** in chat or command output

path: README.md
content: # Zilliz Cloud CLI Skill

A skill that teaches AI agents how to operate [Zilliz Cloud](https://zilliz.com/) and Milvus vector databases through `zilliz-cli`. Instead of memorizing CLI commands, just describe what you want:

- "Create a serverless cluster in us-east-1 and set up a collection with 768-dimension vectors"
- "Search for similar items in my product collection with filter age > 20"
- "Show me the status of all my clusters and collections"
- "Set up a daily backup policy for my production cluster with 7-day retention"
- "Create a role with read-only access to the analytics collection"

## Skill Structure

```
zilliz/
├── SKILL.md                      # Main entry — prerequisites, workflows, safety rules
└── references/                   # Domain-specific command references (loaded on demand)
    ├── setup.md                  # Install, auth, context, config, troubleshooting
    ├── cluster.md                # Cluster create, list, describe, modify, suspend, delete
    ├── collection.md             # Collection CRUD, aliases, load/release
    ├── vector.md                 # Search, query, insert, hybrid search, filter syntax
    ├── index.md                  # Index types, create/drop
    ├── database.md               # Database CRUD (Dedicated clusters only)
    ├── partition.md              # Partition management
    ├── user-role.md              # RBAC: users, roles, privileges
    ├── backup.md                 # Backup/restore, policies
    ├── import.md                 # Bulk data import from cloud storage
    ├── billing.md                # Usage, invoices, payment
    ├── monitoring.md             # Status overview, collection stats
    └── project-region.md         # Projects, volumes, cloud providers
```

## Capabilities

| 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, hybrid search |
| **Indexes** | Create (AUTOINDEX), 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 S3/GCS |
| **Partitions** | Create, load, release, manage |
| **Monitoring** | Cluster status, collection stats, load states |
| **Projects** | Project and region management |
| **Billing** | Usage queries, invoices |

## Installation

### Claude Code

```bash
claude skill add ./zilliz.skill
```

### Manual

Copy the `zilliz/` directory into your skill path and ensure SKILL.md is discoverable by your agent.

## Requirements

- Python 3.10+
- A [Zilliz Cloud](https://cloud.zilliz.com/) account
- `zilliz-cli` (the skill guides installation automatically)

## Origin

Extracted from the [zilliz-plugin](https://github.com/zilliztech/zilliz-plugin) Claude Code plugin. The 13 reference files correspond directly to the plugin's `skills/` directory.

## License

Apache License 2.0


path: references/backup.md
content: 
## Prerequisites

1. CLI installed and logged in (see setup skill).
2. No cluster context required -- backup operations use `--cluster-id` directly.

## Commands Reference

### Create a Backup

```bash
zilliz backup create --cluster-id <cluster-id>
# Optional: --database <database-name>, --collection <collection-name>
# Or use raw JSON: --body '{...}'
```

### List Backups

```bash
zilliz backup list
# Optional:
#   --project-id <filter-by-project-id>
#   --cluster-id <filter-by-cluster-id>
#   --creation-method <manual|auto>
#   --backup-type <CLUSTER|COLLECTION>
# Pagination: --page-size <n> --page <n>
# Fetch all pages: --all
```

### Describe a Backup

```bash
zilliz backup describe --cluster-id <cluster-id> --backup-id <backup-id>
```

### Delete a Backup

```bash
zilliz backup delete --cluster-id <cluster-id> --backup-id <backup-id-to-delete>
```

### Export a Backup

```bash
zilliz backup export \
  --cluster-id <cluster-id> \
  --backup-id <backup-id> \
  --integration-id <storage-integration-id>
# Optional: --directory <directory>
```

### Restore to a New Cluster

```bash
zilliz backup restore-cluster \
  --cluster-id <source-cluster-id> \
  --backup-id <backup-id-to-restore> \
  --project-id <target-project-id> \
  --name <new-cluster-name> \
  --cu-size <compute-units-for-new-cluster> \
  --collection-status <LOADED|NOT_LOADED>
```

### Restore Specific Collections

```bash
zilliz backup restore-collection \
  --cluster-id <source-cluster-id> \
  --backup-id <backup-id> \
  --dest-cluster-id <destination-cluster-id>
# Or use raw JSON: --body '{"collections": [{"source": "col1", "target": "col1_restored"}]}'
```

### Describe Backup Policy

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

### Update Backup Policy

```bash
zilliz backup update-policy --cluster-id <cluster-id> --auto-backup <true|false>
# Optional:
#   --frequency <frequency>
#   --start-time <start-time>
#   --retention-days <days-to-retain-backups>
# Or use raw JSON: --body '{...}'
```

## Backup Policy Format

Frequency: `daily | weekdays | weekends | 1-7` (1=Mon, 7=Sun), e.g. `1,3,5`

Start time: `HH:MM` or `HH:MM-HH:MM` (time window), e.g. `02:00` or `03:00-05:00`

## Guidance

- The backup type is automatically derived: if `--collection` is provided, it's a COLLECTION backup; otherwise it's a CLUSTER backup.
- Backup creation, export, and restore operations are **asynchronous**. After starting, use `backup describe` to check progress.
- The `--integration-id` for export refers to a cloud storage integration configured in the Zilliz Cloud console (see import skill for setup guidance).
- Before deleting a backup, confirm with the user -- this is irreversible.
- When restoring, explain the difference between cluster restore (new cluster) and collection restore (into existing cluster).
- Suggest setting up a backup policy for production clusters.


path: references/billing.md
content: 
## Prerequisites

1. CLI installed and logged in via OAuth (see setup skill).
2. Billing features require OAuth login -- API Key mode may not have access.

## Commands Reference

### Query Usage

```bash
# Last N days
zilliz billing usage --last 7d

# Current month
zilliz billing usage --month this

# Last month
zilliz billing usage --month last

# Specific month
zilliz billing usage --month 2026-01

# Custom date range
zilliz billing usage --start 2026-01-01 --end 2026-01-31
```

### List Invoices

```bash
# List all invoices (paginated)
zilliz billing invoices

# Fetch all pages
zilliz billing invoices --all

# Paginate manually
zilliz billing invoices --page-size 10 --page 1
```

### View Invoice Details

```bash
zilliz billing invoices --invoice-id inv-xxxxxxxxxxxx
```

### Bind a Credit Card

```bash
zilliz billing bind-card \
  --card-number <credit-card-number> \
  --exp-month <expiration-month> \
  --exp-year <expiration-year> \
  --cvc <card-verification-code>
```

## Guidance

- Billing commands require OAuth login, not API Key authentication.
- When the user asks about costs or spending, use `billing usage` with an appropriate time range.
- The `bind-card` command handles sensitive card data -- always instruct the user to run it in their own terminal, never inside Claude Code.


path: references/cluster.md
content: 
## Prerequisites

1. CLI installed and logged in (see setup skill).
2. No cluster context required -- these are control-plane operations.

## Commands Reference

### Create a Cluster

```bash
# Serverless cluster
zilliz cluster create \
  --name <cluster-name> \
  --type serverless \
  --project-id <project-id> \
  --region <region-id>

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

# Dedicated cluster
zilliz cluster create \
  --name <cluster-name> \
  --type dedicated \
  --project-id <project-id> \
  --region <region-id> \
  --cu-type <Performance-optimized|Capacity-optimized> \
  --cu-size <cu-size>
```

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

```bash
zilliz project list
zilliz cluster providers
zilliz cluster regions --cloud-id <aws|gcp|azure>
```

### List Clusters

```bash
zilliz cluster list
# Pagination: --page-size <n> --page <n>
# Fetch all pages: --all
```

### Describe a Cluster

```bash
zilliz cluster describe --cluster-id <cluster-id>
```

### Modify a Cluster

```bash
zilliz cluster modify --cluster-id <cluster-id-to-modify>
# Optional: --cu-size <number-of-compute-units>, --replica <number-of-replicas>
# Or use raw JSON: --body '{"cuSize": 2, "replica": 2}'
```

### Suspend a Cluster

```bash
zilliz cluster suspend --cluster-id <cluster-id-to-suspend>
```

### Resume a Cluster

```bash
zilliz cluster resume --cluster-id <cluster-id-to-resume>
```

### Delete a Cluster

```bash
zilliz cluster delete --cluster-id <cluster-id-to-delete>
```

### List Cloud Providers

```bash
zilliz cluster providers
```

### List Regions

```bash
zilliz cluster regions
# Optional: --cloud-id <aws|gcp|azure>
```

## 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`, the cluster status will be `CREATING`. Poll with `zilliz cluster describe --cluster-id <id>` until the status becomes `RUNNING` before proceeding with data-plane operations.
- Before deleting a cluster, always confirm with the user -- this is irreversible.
- After creating a cluster, suggest setting it as the active context with `zilliz context set --cluster-id <id>`.
- When a cluster is suspended, remind the user it must be resumed before data-plane operations.
- Different cluster types have different capabilities. See the "Cluster Type Differences" table in the setup skill for details.


path: references/collection.md
content: 
## Prerequisites

1. CLI installed, logged in, and cluster context set (see setup skill).

## Commands Reference

All collection commands accept an optional `--database <db-name>` flag to target a non-default database. If omitted, the database from the current context is used.

### Create a Collection

```bash
zilliz collection create --name <collection-name> --dimension <vector-dimension>
# Optional:
#   --metric-type <COSINE|L2|IP>
#   --id-type <Int64|VarChar>
#   --auto-id <true|false>
#   --primary-field <primary-key-field-name>
#   --vector-field <vector-field-name>
#   --database <database-name>
# Or use raw JSON: --body '{"schema": {"fields": [{"fieldName": "id", "dataType": "Int64", "isPrimary": true}, {"fieldName": "vector", "dataType": "FloatVector", "elementTypeParams": {"dim": "768"}}]}}'
```

### List Collections

```bash
zilliz collection list
# Optional: --database <database-name>
```

### Describe a Collection

```bash
zilliz collection describe --name <collection-name>
# Optional: --database <database-name>
```

### Drop a Collection

```bash
zilliz collection drop --name <collection-name-to-drop>
# Optional: --database <database-name>
```

### Rename a Collection

```bash
zilliz collection rename --name <current-collection-name> --new-name <new-collection-name>
# Optional: --database <current-database-name>, --new-database <target-database-name>
```

### Load a Collection

```bash
zilliz collection load --name <collection-name>
# Optional: --database <database-name>
```

### Release a Collection

```bash
zilliz collection release --name <collection-name>
# Optional: --database <database-name>
```

### Get Load State

```bash
zilliz collection get-load-state --name <collection-name>
# Optional: --database <database-name>
```

### Get Statistics

```bash
zilliz collection get-stats --name <collection-name>
# Optional: --database <database-name>
```

### Check if a Collection Exists

```bash
zilliz collection has --name <collection-name>
# Optional: --database <database-name>
```

### Flush a Collection

```bash
zilliz collection flush --name <collection-name>
# Optional: --database <database-name>
```

### Compact a Collection

```bash
zilliz collection compact --name <collection-name>
# Optional: --database <database-name>
```

### Collection Aliases

#### Create an Alias

```bash
zilliz alias create --collection <target-collection-name> --alias <alias-name>
# Optional: --database <database-name>
```

#### List Aliases

```bash
zilliz alias list --database <database-name>
# Optional: --collection <filter-by-collection-name>
```

#### Describe an Alias

```bash
zilliz alias describe --alias <alias-name>
# Optional: --database <database-name>
```

#### Alter an Alias

```bash
zilliz alias alter --collection <new-target-collection> --alias <alias-name-to-reassign>
# Optional: --database <database-name>
```

#### Drop an Alias

```bash
zilliz alias drop --alias <alias-name-to-drop>
# Optional: --database <database-name>
```

## Guidance

- When the user wants to create a collection, ask about their use case to recommend appropriate dimension, metric type, and schema.
- Before dropping a collection, always confirm with the user -- this deletes all data.
- A collection must be loaded before it can be searched or queried.
- After creating a collection, suggest loading it if the user plans to query immediately.
- Use `describe` to inspect schema before performing vector operations.


path: references/database.md
content: 
## Prerequisites

1. CLI installed, logged in, and cluster context set (see setup skill).

## Commands Reference

### Create a Database

```bash
zilliz database create --name <database-name>
# Or use raw JSON: --body '{"properties": {}}'
```

*Create a new database. (Dedicated only)*

### List Databases

```bash
zilliz database list
```

### Describe a Database

```bash
zilliz database describe --name <database-name>
```

*Get details of a database. (Dedicated only)*

### Drop a Database

```bash
zilliz database drop --name <database-name-to-drop>
```

*Drop a database. (Dedicated only)*

## Guidance

- Database create, describe, and drop operations 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>`.
- To work with collections in a non-default database, use `--database` flag on collection commands or switch context.


path: references/import.md
content: 
## Prerequisites

1. CLI installed and logged in (see setup skill).
2. Target collection must exist on the target cluster.

## Commands Reference

### Start an Import Job

```bash
zilliz import start --cluster-id <target-cluster-id> --collection <target-collection-name>
# Or use raw JSON: --body '{"files": [["s3://bucket/path/data.parquet"]]}'
```

### List Imports

```bash
zilliz import list --cluster-id <cluster-id>
# Optional: --database <database-name>
```

### Check Import Status

```bash
zilliz import status --job-id <import-job-id> --cluster-id <cluster-id>
```

## Integration Setup

Import requires a cloud storage integration to access data files. The `integration-id` is configured in the Zilliz Cloud console under **Project Settings > Integrations**. Ensure the integration has read access to the source bucket and path.

Supported file formats: Parquet, JSON, CSV.

## Guidance

- Import jobs run asynchronously. After starting a job, use `import status` to track progress.
- The data files must be accessible from Zilliz Cloud (e.g., S3, GCS with proper integration configured).
- The collection schema must match the data file structure.


path: references/index.md
content: 
## Prerequisites

1. CLI installed, logged in, and cluster context set (see setup skill).
2. Target collection must exist (see collection skill).

## Commands Reference

All index commands accept an optional `--database <db-name>` flag. If omitted, the database from the current context is used.

### Create an Index

```bash
zilliz index create --collection <collection-name>
# Optional: --database <database-name>
# Or use raw JSON: --body '{"indexParams": [{"fieldName": "vector", "indexType": "AUTOINDEX", "metricType": "COSINE"}]}'
```

### List Indexes

```bash
zilliz index list --collection <collection-name>
# Optional: --database <database-name>
```

### Describe an Index

```bash
zilliz index describe --collection <collection-name> --index-name <index-name>
# Optional: --database <database-name>
```

### Drop an Index

```bash
zilliz index drop --collection <collection-name> --index-name <index-name-to-drop>
# Optional: --database <database-name>
```

## Index Types

Common index types:
- `AUTOINDEX` -- recommended, automatically selects the best index
- `IVF_FLAT`, `IVF_SQ8`, `HNSW` -- manual selection for advanced users

Common metric types:
- `COSINE` -- cosine similarity (default)
- `L2` -- Euclidean distance
- `IP` -- inner product

## Guidance

- On Zilliz Cloud, `AUTOINDEX` is recommended for most use cases.
- An index is required before loading a collection for search.
- Before creating an index, check the collection schema to identify vector fields.
- After creating an index, remind the user to load the collection.


path: references/monitoring.md
content: 
## Prerequisites

1. CLI installed and logged in (see setup skill).
2. Cluster context set for collection-level monitoring (see setup skill).

## Commands Reference

All monitoring commands that target collections accept an optional `--database <db-name>` flag. If omitted, the database from the current context is used.

### Cluster Status

```bash
# Current context
zilliz context current

# Cluster details (status, plan, region, endpoints)
zilliz cluster describe --cluster-id <cluster-id>
```

### Collection Overview

List all collections with their stats:

```bash
# List collections
zilliz collection list
zilliz collection list --database <db-name>

# For each collection, get stats and load state:
zilliz collection get-stats --name <collection-name>
zilliz collection get-load-state --name <collection-name>
```

If the cluster has multiple databases, iterate through each database by running `zilliz database list` first, then `zilliz collection list --database <db-name>` for each.

### Database Overview

```bash
zilliz database list
```

### All Clusters

```bash
zilliz cluster list --all
```

## Presenting Results

When the user asks for a status overview, collect and present information as a summary table:

**Cluster Info:**
- Cluster ID, name, status (RUNNING/SUSPENDED/etc.)
- Plan type, region, create time

**Collections Summary:**
Present as a table with columns:
| Collection | Rows | Load State |
|---|---|---|

Gather this by running `collection list`, then `get-stats` and `get-load-state` for each collection.

## Guidance

- When presenting status, use `--output json` to get machine-readable data, then format it into a readable summary for the user.
- If the cluster is suspended, note this prominently and inform the user that data-plane operations are unavailable.
- For multiple clusters, show a summary table of all clusters first, then drill into the selected one.


path: references/partition.md
content: 
## Prerequisites

1. CLI installed, logged in, and cluster context set (see setup skill).
2. Target collection must exist (see collection skill).

## Commands Reference

All partition commands accept an optional `--database <db-name>` flag. If omitted, the database from the current context is used.

### Create a Partition

```bash
zilliz partition create --collection <collection-name> --partition <partition-name>
# Optional: --database <database-name>
```

### List Partitions

```bash
zilliz partition list --collection <collection-name>
# Optional: --database <database-name>
```

### Drop a Partition

```bash
zilliz partition drop --collection <collection-name> --partition <partition-name-to-drop>
# Optional: --database <database-name>
```

### Check if a Partition Exists

```bash
zilliz partition has --collection <collection-name> --partition <partition-name>
# Optional: --database <database-name>
```

### Get Statistics

```bash
zilliz partition get-stats --collection <collection-name> --partition <partition-name>
# Optional: --database <database-name>
```

### Load a Partition

```bash
zilliz partition load --collection <collection-name> --names '["partition1", "partition2"]'
# Optional: --database <database-name>
```

### Release a Partition

```bash
zilliz partition release --collection <collection-name> --names '["partition1", "partition2"]'
# Optional: --database <database-name>
```

## Guidance

- Every collection has a default `_default` partition.
- Partitions allow organizing data for more targeted searches.
- A partition must be loaded before it can be searched.
- Before dropping a partition, confirm with the user -- all data in it will be deleted.
- Use partition stats to check row counts per partition.
- For filter expression syntax used in vector operations on partitions, see the vector skill.


path: references/project-region.md
content: 
## Prerequisites

1. CLI installed and logged in (see setup skill).

## Commands Reference

### Projects

#### Create a Project

```bash
zilliz project create --name <project-name> --plan <Free|Serverless|Standard|Enterprise>
```

#### List Projects

```bash
zilliz project list
```

#### Describe a Project

```bash
zilliz project describe --project-id <project-id>
```

#### Upgrade a Project

```bash
zilliz project upgrade --project-id <project-id>
# Optional: --plan <Serverless|Standard|Enterprise>
```

### Volumes

#### Create a Volume

```bash
zilliz volume create \
  --project-id <project-id> \
  --region <cloud-region> \
  --name <volume-name>
```

#### List Volumes

```bash
zilliz volume list --project-id <project-id>
# Pagination: --page-size <n> --page <n>
# Fetch all pages: --all
```

#### Delete a Volume

```bash
zilliz volume delete --name <volume-name-to-delete>
```

## Guidance

- When the user wants to create a cluster, they need a project ID and region ID first. Guide them through `zilliz project list` and `zilliz cluster regions` (see cluster skill).
- Project `upgrade` does not include `Free` as a valid target plan -- only Serverless, Standard, and Enterprise.
- Before deleting a volume, confirm with the user.


path: references/setup.md
content: 
## 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.

## Commands Reference

### 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 Claude Code. 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. Use this when you need to parse results programmatically:

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

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

## Cluster Type Differences

Different cluster types have different feature support:

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

When a command fails with a permissions error, check the cluster type first — the feature may not be available on that cluster type.

## Troubleshooting

- **"command not found" after install:** Check that the Python scripts directory is in your PATH. Try running `python3 -m zilliz` as an alternative.
- **"not authenticated" errors:** Run `zilliz auth status` to check login state. Tokens may have expired — re-run login in your own terminal.
- **Context errors (no cluster set):** Run `zilliz context current` to verify. If the cluster was deleted or suspended, set a new context with `zilliz context set --cluster-id <id>`.
- **Permission or "not supported" errors:** Check the cluster type — some operations are only available on Dedicated clusters (see Cluster Type Differences table above).
- **Network or timeout errors:** Verify the cluster is RUNNING with `zilliz cluster describe --cluster-id <id>`. Suspended clusters reject data-plane requests.

## Guidance

- Always check prerequisites before executing any command.
- If a prerequisite fails, fix it before proceeding — do not skip ahead.
- NEVER run `zilliz login`, `zilliz configure`, or `zilliz auth switch` (without arguments) inside Claude Code — they require interactive input. Always instruct the user to run these in their own terminal.
- NEVER ask the user to paste API keys into the chat — this is a security risk. Guide them to configure credentials in their own terminal instead.
- After the user reports login is complete, verify with `zilliz auth status`.
- After setting context, verify with `zilliz context current`.
- For data-plane commands in other skills, always verify context is set first.
- When a command fails unexpectedly, consider whether the cluster type or auth mode may be the cause.


path: references/user-role.md
content: 
## Prerequisites

1. CLI installed, logged in, and cluster context set (see setup skill).

## Commands Reference

### Users

#### Create a User

```bash
zilliz user create --user <username> --password <password>
```

#### List Users

```bash
zilliz user list
```

#### Describe a User

```bash
zilliz user describe --user <username>
```

#### Drop a User

```bash
zilliz user drop --user <username-to-drop>
```

#### Update Password

```bash
zilliz user update-password \
  --user <username> \
  --password <current-password> \
  --new-password <new-password>
```

#### Grant a Role to a User

```bash
zilliz user grant-role --user <username> --role <role-name-to-grant>
```

#### Revoke a Role from a User

```bash
zilliz user revoke-role --user <username> --role <role-name-to-revoke>
```

### Roles

#### Create a Role

```bash
zilliz role create --role <role-name>
```

#### List Roles

```bash
zilliz role list
```

#### Describe a Role

```bash
zilliz role describe --role <role-name>
```

#### Drop a Role

```bash
zilliz role drop --role <role-name-to-drop>
```

#### Grant a Privilege

```bash
zilliz role grant-privilege \
  --role <role-name> \
  --object-type <Global|Collection|Database> \
  --object-name <object-name> \
  --privilege <privilege-name>
# Optional: --database <database-name>
```

#### Revoke a Privilege

```bash
zilliz role revoke-privilege \
  --role <role-name> \
  --object-type <Global|Collection|Database> \
  --object-name <object-name> \
  --privilege <privilege-name>
# Optional: --database <database-name>
```

## Common Privileges

Common privileges by object type:

- **Collection**: `Search`, `Query`, `Insert`, `Delete`, `CreateIndex`, `DropCollection`
- **Global**: `CreateCollection`, `All`
- **Database**: `ListCollections`

## Guidance

- User and role management is only available on **Dedicated** clusters.
- Built-in roles: `admin` (full access), `public` (no privileges by default -- must be granted explicitly).
- When setting up RBAC, suggest a workflow: create role, grant privileges, create user, assign role.
- Before dropping a user or role, confirm with the user.
- Use `*` as object-name to grant privilege on all objects of that type.


path: references/vector.md
content: 
## Prerequisites

1. CLI installed, logged in, and cluster context set (see setup skill).
2. Target collection must exist and be loaded (see collection skill).

## Commands Reference

All vector commands accept an optional `--database <db-name>` flag to target a non-default database. If omitted, the database from the current context is used.

### Insert Vectors

```bash
zilliz vector insert --collection <collection-name> --data '[{"id": 1, "vector": [0.1, 0.2, ...], "text": "hello"}]'
# Optional: --database <database-name>
# Or use raw JSON: --body '{...}'
```

### Upsert Vectors

```bash
zilliz vector upsert --collection <collection-name> --data '[{"id": 1, "vector": [0.1, 0.2, ...], "text": "hello"}]'
# Optional: --partition <partition-name>, --database <database-name>
# Or use raw JSON: --body '{...}'
```

### Vector Search

```bash
zilliz vector search --collection <collection-name> --data '[[0.1, 0.2, 0.3, ...]]'
# Optional:
#   --anns-field <vector-field-to-search-on>
#   --limit <max-results-to-return>
#   --filter <scalar-filter-expression>
#   --output-fields '["field1", "field2"]'
#   --database <database-name>
```

### Hybrid Search

```bash
zilliz vector hybrid-search \
  --collection <collection-name> \
  --search '[{"data": [[0.1, ...]], "annsField": "dense_vector", "limit": 10}, {"data": [["search text"]], "annsField": "sparse_vector", "limit": 10}]' \
  --rerank '{"strategy": "rrf", "params": {"k": 60}}'
# Optional:
#   --limit <max-results-to-return>
#   --output-fields '["field1", "field2"]'
#   --database <database-name>
# Or use raw JSON: --body '{...}'
```

### Query by Filter

```bash
zilliz vector query --collection <collection-name> --filter <scalar-filter-expression>
# Optional:
#   --limit <max-results-to-return>
#   --output-fields '["field1", "field2"]'
#   --database <database-name>
```

### Get by ID

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

### Delete a Vector

```bash
zilliz vector delete --collection <collection-name> --filter <filter>
# Optional: --partition <partition-name>, --database <database-name>
```

## Filter Expression Syntax

Common filter patterns:

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

## Guidance

- The `--data` parameter accepts a JSON array of vectors. Each vector is an array of floats.
- Before searching, inspect the collection schema with `zilliz collection describe` to understand field names and vector dimensions.
- The collection must be loaded before search/query operations.
- For search, the `--data` value must match the collection's vector dimension exactly.
- Use `--anns-field` to specify which vector field to search on when the collection has multiple vector fields.
- When the user provides a text query and wants semantic search, explain that they need to convert text to vectors first (using an embedding model) before passing to `--data`.
- For large insert operations, suggest writing data to a JSON file first, then using `zilliz vector insert --collection <name> --data "$(cat data.json)"`.
- Always show `--output-fields` when the user wants specific fields in results.
- Or use `--body` for complex hybrid search configurations.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)