Zilliz

View saved version →

---
name: backup
description: Use when the user wants to create, list, describe, delete, export, or restore backups, or manage backup policies on Zilliz Cloud.
---

## 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>
#   --backup-type <CLUSTER|COLLECTION>
# 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.

View saved version →

---
name: billing
description: Use when the user wants to check usage, view invoices, or manage payment methods on Zilliz Cloud.
---

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



## 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.
- To bind a credit card, direct the user to the Zilliz Cloud web console -- card binding is not available via CLI for security reasons.

View saved version →

---
name: cluster
description: Use when the user wants to create, list, describe, delete, suspend, resume, or modify Zilliz Cloud clusters.
---

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

### Create a Vector Lake instance

A Vector Lake (sometimes called a "VectorLake" cluster) is the storage layer
that on-demand clusters attach to (see the `on-demand-cluster` skill). It is
created via a hand-written subcommand calling
`POST /v2/clusters/createVectorLake`:

```bash
zilliz cluster create-vectorlake \
  --project-id <project-id> \
  --region-id <region-id> \
  [--session-ttl <duration>] \      # idle auto-suspend TTL, min 60s
  [--max-query-node-cu <integer>] \
  [--max-query-node-replicas <integer>]
```

After the Vector Lake is `RUNNING`, attach a query workload with
`zilliz on-demand-cluster create --project-id <id> --region-id <region> --cu-size <n> --cluster-name <name>`.

### List Clusters

```bash
zilliz cluster list
# Optional: --region-id <filter-by-region-id>
# 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.
- `cluster create-vectorlake` creates a Vector Lake storage instance, not a regular cluster. Query workloads against it run on on-demand clusters (see the `on-demand-cluster` skill). Do not pass `--type` to this subcommand; it has its own dedicated parameter set.
- `cluster list` supports a `--region-id <region>` filter for scoping to a single region.

View saved version →

---
name: collection
description: Use when the user wants to create, list, describe, drop, rename, load, release, or manage collections and collection aliases in Milvus.
---

## Prerequisites

1. CLI installed, a usable data-plane credential configured, 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.

## Collection metrics

Query per-collection metrics against `POST /v2/clusters/{clusterId}/metrics/query` with `collectionName` set in the request body. Mirrors the web console's Collection Detail > Metrics page.

```bash
zilliz collection metrics --collection-name <collection-name> --metric <metric-name>
# Optional:
#   --cluster-id <cluster-id>         Override cluster context
#   --period <duration>               e.g. 1h, 24h, 7d (mutually exclusive with --start/--end)
#   --start <iso-8601> --end <iso-8601>
#   --granularity <duration> / -g     e.g. 30s, 5m, 1h (auto-selected if omitted)
#   -o table                          Render pivot table instead of the default inline chart
```

The default output is an inline text chart: one block per metric with a summary line (`min / max / avg / last`) and a Braille-rendered line chart. Pass an explicit `-o table` (or `--output table`) to render the pivot-table layout — useful for terminals without good Braille font support. `-o json`, `-o yaml`, `-o csv`, and `--query` always bypass both renderers and return the raw response.

Examples:

```bash
# Period shorthand: last hour of SEARCH_QPS for a collection
zilliz collection metrics -c my_coll -m SEARCH_QPS --period 1h

# Explicit range with 1h granularity
zilliz collection metrics -c my_coll -m ENTITIES_LOADED \
  --start 2026-04-13T00:00:00Z --end 2026-04-14T00:00:00Z -g 1h

# Multiple metrics in a single call
zilliz collection metrics -c my_coll -m SEARCH_QPS -m SEARCH_LATENCY_P99 --period 6h
```

### Metric scope

Each metric is tagged with a scope. `zilliz collection metrics` only accepts metrics whose scope is `Collection` or `Both`. Using a Cluster-only metric emits:

```
Metric '<NAME>' is cluster-scope only and cannot be used with --collection-name.
```

| Scope | Metrics |
|-------|---------|
| Cluster only (rejected here) | `CU_COMPUTATION`, `CU_CAPACITY`, `CU_SIZE`, `REPLICA_COUNT`, `STORAGE`, `COLLECTIONS`, `SLOW_QUERIES`, `READ_VCU`, `WRITE_VCU` |
| Collection / Both (allowed) | `SEARCH_QPS`, `QUERY_QPS`, `INSERT_QPS`, `UPSERT_QPS`, `DELETE_QPS`, `BULK_INSERT_QPS`, `SEARCH_LATENCY_AVG/P99`, `QUERY_LATENCY_AVG/P99`, `INSERT_LATENCY_AVG/P99`, `UPSERT_LATENCY_AVG/P99`, `DELETE_LATENCY_AVG/P99`, VPS counters, failure-rate counters, `ENTITIES`, `ENTITIES_LOADED`, `ENTITIES_INDEXED`, plus the hybrid-search aliases below |

### Hybrid-search aliases

| CLI name | Backend name |
|----------|--------------|
| `HYBRID_SEARCH_QPS` | `REQ_HYBRID_SEARCH_COUNT` |
| `HYBRID_SEARCH_LATENCY_AVG` | `REQ_HYBRID_SEARCH_LATENCY_AVG` |
| `HYBRID_SEARCH_LATENCY_P99` | `REQ_HYBRID_SEARCH_LATENCY_P99` |
| `HYBRID_SEARCH_FAIL_RATE` | `REQ_FAIL_RATE_HYBRID_SEARCH` |

For cluster-wide metrics (CU sizing, storage, serverless VCU, slow queries) use `zilliz cluster metrics` instead -- see the monitoring skill.

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

View saved version →

---
name: database
description: Use when the user wants to create, list, describe, or drop databases in Milvus.
---

## Prerequisites

1. CLI installed, a usable data-plane credential configured, 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": {}}'
```

Availability depends on the current endpoint, credential, and service configuration. Report the CLI or server response without inferring support from a cluster label alone.

### List Databases

```bash
zilliz database list
```

### Describe a Database

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

If details are unavailable, fall back to the information returned by `database list` and the current context.

### Drop a Database

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

This action is destructive. Confirm the exact database and impact immediately before execution.

## Guidance

- Use `database list` and the current context to discover available database names. Do not assume that a database named `default` exists or is accessible.
- When an operation is rejected, report the returned permission or availability error and continue with independent database capabilities where possible.
- 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.

View saved version →

---
name: diagnose
description: Use when the user reports that a Zilliz Cloud cluster or Milvus collection is unhealthy, slow, stuck, returning errors, hitting quotas, or otherwise misbehaving — or when they ask "what's wrong with...", "why is ... slow", "diagnose ...", "troubleshoot ...".
---

## Prerequisites

1. CLI installed and logged in (see setup skill).
2. For cluster diagnosis: a cluster context, or pass `--cluster-id` explicitly.
3. For collection diagnosis: the cluster context must point at the cluster that owns the collection (see setup skill).

## Scope

This skill performs **read-only diagnosis** using existing `zilliz` commands. It does NOT mutate clusters, collections, indexes, or data. Every recommendation is presented as a suggestion plus the exact next command the user can run themselves.

Two entry points:

| User says | Use section |
|---|---|
| "diagnose my cluster", "cluster is slow / stuck / unhealthy" | [Cluster Diagnosis](#cluster-diagnosis) |
| "diagnose this collection", "search is slow on X", "X won't load" | [Collection Diagnosis](#collection-diagnosis) |

When the user's intent spans both (e.g. "everything is slow"), run cluster diagnosis first — a collection-level symptom often has a cluster-level cause.

## Cluster Diagnosis

Follow this checklist in order. Stop early only if you find a P0 problem (cluster not RUNNING, quota hard-stop) — surface it before running the rest.

### 1. Collect

Run these in parallel where possible and prefer `-o json` for machine parsing:

```bash
zilliz context current
zilliz cluster describe --cluster-id <id> -o json
zilliz cluster list --all -o json                       # peer clusters for context
zilliz billing usage -o json                            # quota / spend headroom
```

Then pull time-series metrics covering the last hour and last 24h. Use the chart output for human review and `-o json` if you need to compute thresholds:

```bash
zilliz cluster metrics --cluster-id <id> \
  -m CU_COMPUTATION -m CU_CAPACITY -m CU_SIZE -m REPLICA_COUNT \
  -m STORAGE -m SLOW_QUERIES \
  -m SEARCH_QPS -m SEARCH_LATENCY_P99 \
  -m SEARCH_FAIL_RATE -m INSERT_FAIL_RATE \
  --period 1h
```

Repeat with `--period 24h` for trend context.

### 2. Analyze

Walk each rule. Each finding must cite the evidence (command + observed value).

| Check | Evidence | If true, suggest |
|---|---|---|
| Cluster status ≠ RUNNING | `cluster describe` `.status` | Pause diagnosis; explain status; if SUSPENDED suggest `cluster resume` |
| Plan vs. observed QPS mismatch (e.g. Serverless under sustained high QPS) | plan + `SEARCH_QPS` | Discuss plan upgrade tradeoff |
| `CU_COMPUTATION` p95 > 80% of `CU_CAPACITY` for sustained windows | metric series | Recommend scaling CU or adding replicas |
| `SEARCH_LATENCY_P99` rising while QPS flat | latency vs qps | Likely index/CU pressure; drill into top collections |
| Non-zero `*_FAIL_RATE` | fail-rate series | Cross-check with recent user-reported errors |
| `SLOW_QUERIES` non-zero | metric | Drill into per-collection diagnosis for the offenders |
| Storage trending toward quota | `STORAGE` + billing | Suggest cleanup / plan change before hard cap |
| Region likely far from client | endpoint + user-reported RTT | Note possible region mismatch — cannot measure RTT from CLI |

### 3. Present

Render a single report with three sections, in this order:

1. **Summary** — one-line health verdict (healthy / degraded / critical) + 1-3 sentence rationale.
2. **Findings** — table with columns `Severity | Finding | Evidence | Suggested Next Step`.
3. **Suggested commands** — copy-pasteable `zilliz ...` commands matching each suggestion. Never run mutating commands yourself — let the user run them.

## Collection Diagnosis

### 1. Collect

```bash
zilliz collection describe --name <coll> -o json
zilliz collection get-stats --name <coll> -o json
zilliz collection get-load-state --name <coll> -o json
zilliz index list --collection-name <coll> -o json
# For each vector index reported above:
zilliz index describe --collection-name <coll> --field-name <field> -o json
zilliz partition list --collection-name <coll> -o json
```

Pull per-collection metrics for the last hour and 24h:

```bash
zilliz collection metrics -c <coll> \
  -m SEARCH_QPS -m SEARCH_LATENCY_P99 -m SEARCH_FAIL_RATE \
  -m QUERY_QPS -m QUERY_LATENCY_P99 \
  -m INSERT_QPS -m INSERT_LATENCY_P99 \
  -m ENTITIES -m ENTITIES_LOADED -m ENTITIES_INDEXED \
  --period 1h
```

If the cluster context is wrong or the collection lives in a non-default database, pass `--database <db>` on every command.

### 2. Analyze

| Check | Evidence | If true, suggest |
|---|---|---|
| Load state ≠ Loaded (or partially loaded) | `get-load-state` | `collection load --name <coll>`; explain that unloaded collections cannot serve search |
| `ENTITIES_LOADED` ≪ `ENTITIES` | metrics | Load incomplete or recently grew; wait or reload |
| `ENTITIES_INDEXED` ≪ `ENTITIES` | metrics | Indexing lag; investigate before tuning |
| Vector field present but no vector index, or FLAT on large row count | `index list` + `get-stats` | Recommend HNSW / IVF_* with a parameter range appropriate for row count; mark as recommendation, not absolute |
| Index params clearly off (e.g. `nlist` ≪ √N for IVF) | `index describe` + row count | Suggest revised values; note that benchmarking is needed for the final number |
| Replica count = 1 with sustained high QPS | `collection describe` replicas + `SEARCH_QPS` | Suggest more replicas, conditioned on CU headroom from cluster diagnosis |
| Schema reasons: very wide varchar, many un-indexed scalar fields used in filters | `collection describe` schema | Note impact; suggest scalar indexes where applicable |
| No partition key but row count is large and queries are naturally partitionable | schema | Mention partition-key option (cannot be added in place — design-time decision) |
| Non-zero `SEARCH_FAIL_RATE` | metric | Cross-check with cluster-level fail-rate metrics |
| Latency rising while QPS flat | latency vs qps | Index pressure or growing segment count; consider compaction; note that segment-level state is not exposed via CLI |

### 3. Present

Same three-section format as cluster diagnosis. When a collection finding's true root cause is at the cluster level (e.g. CU saturation), say so explicitly and reference the cluster report.

## Guidance

- **Read-only.** Never run `delete`, `drop`, `release`, `resume`, `suspend`, `create`, `update`, index create/drop, or any mutating data-plane command as part of diagnosis. Present them as suggestions only.
- **Cite evidence.** Every finding must reference the command that produced it and the observed value. No unsourced claims.
- **Mark uncertainty.** Index parameter recommendations, replica counts, and CU sizing depend on workload specifics the CLI cannot observe. Phrase as "starting point, benchmark to confirm."
- **Know the limits.** The CLI cannot see per-query plans, segment-level state, compaction backlog, GC, server-internal queues, or alert-rule state. If a question requires those, say so plainly rather than guessing.
- **Prefer parallel collection.** When multiple read-only commands are independent, run them in parallel to keep the diagnosis fast.
- **JSON for parsing, charts for humans.** Use `-o json` (optionally with `--query`) when comparing values against thresholds; use the default chart output when surfacing trends back to the user.
- **Honor context.** If the user has multiple clusters, confirm which one before collecting. If the collection is in a non-default database, thread `--database` through every command.

View saved version →

---
name: external-collection
description: Use when the user wants to trigger, describe, or list refresh jobs for an external collection (a collection backed by an external data source such as Vector Lake). Note this is the data-plane refresh workflow, not collection CRUD -- for create/drop/load see the collection skill.
---

## Prerequisites

1. CLI installed, logged in, and cluster context set (see setup skill).
2. The target collection must already exist as an **external collection**
   (created with an `externalSource` / `externalSpec` schema in the
   collection skill). Plain in-place collections do not have refresh jobs.
3. The cluster must be running a `kite-coordinator` build that exposes
   `/v2/vectordb/jobs/external_collection/*` (PR #5735 or later). On older
   data planes the API returns 404 -- in that case ask the user to upgrade
   the cluster.

## Commands Reference

The `external-collection` resource has a single operation, `refresh`, with
three actions: `trigger`, `describe`, and `list`. All three are data-plane
calls and inherit the database from the current context unless overridden
with `--database`.

### Trigger a refresh job

```bash
zilliz external-collection refresh trigger --name <collection-name>
# Optional:
#   --database <db-name>          Override the context database
#   --external-source <src>       Override the external source registered on the collection
#   --external-spec <spec>        Override the external spec registered on the collection
```

`trigger` returns the new `jobId`. Use it with `refresh describe` to poll
status. The override flags are intentionally rare -- normally the source
and spec are pinned at collection-create time, and a plain
`refresh trigger --name <name>` is enough.

### Describe a refresh job

```bash
zilliz external-collection refresh describe --job-id <id>
```

Returns the job's state, progress, and (on failure) the error message.

### List refresh jobs

```bash
zilliz external-collection refresh list
# Optional:
#   --name <collection-name>      Filter to one external collection
#   --database <db-name>          Override the context database
```

Without filters, `list` returns recent refresh jobs scoped to the current
database. Pair with `--query` to extract a single field, e.g.:

```bash
zilliz external-collection refresh list --name my_external_coll \
  --query 'data[?state==`Pending` || state==`Running`].jobId'
```

## Guidance

- An external collection is a collection whose rows live in an external
  source (e.g. a Vector Lake table). The collection's metadata, indexes,
  and schema are in Milvus, but the data is pulled in on demand. The
  `refresh` job is what synchronises that external data into the
  collection so subsequent queries see fresh rows.
- Refresh jobs are asynchronous. After `trigger`, poll with `describe`
  until the job reaches a terminal state. Do not assume completion just
  because `trigger` returned successfully -- that only means the job was
  accepted.
- If `trigger` fails with "collection not found" or "not an external
  collection", verify with `zilliz collection describe --name <name>`
  that the collection actually has an `externalSource` field. If it
  does not, this is a normal in-place collection and refresh does not
  apply -- nothing needs to be done.
- When `describe` reports a failed job, surface the error message to the
  user verbatim. It usually points at a credentials, network, or schema
  mismatch in the external source rather than a Milvus bug.
- Avoid scheduling overlapping refresh jobs against the same collection
  -- check `list --name <name>` for an already-running job before
  triggering a new one.
- A `trigger` on a large external table can run for minutes. Do not
  hold a chat session open polling every few seconds -- give the user
  the `jobId` and explain how to come back and check `describe` later.
- For related operations on the same collection (create, drop, load,
  query) defer to the `collection` skill. This skill only covers the
  refresh lifecycle.

View saved version →

---
name: import
description: Use when the user wants to import bulk data into a Milvus collection via Zilliz Cloud import jobs, or manage import stages (pre-uploaded file holders that import jobs reference).
---

## Prerequisites

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

## Commands Reference

### Import Jobs

#### Start an Import Job

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

#### List Imports

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

#### Check Import Status

```bash
zilliz import status --job-id <import-job-id>
# Optional:
#   --cluster-id <cluster-id>
#   --project-id <project-id>
#   --region-id <region-id>
```

### Import Stages

#### List Stages

```bash
zilliz stage list
# Optional: --project-id <filter-by-project-id>
# Pagination: --page-size <n> --page <n>
# Fetch all pages: --all
```

#### Create a Stage

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

#### Delete a Stage

```bash
zilliz stage delete --stage-name <stage-name>
```

#### Apply

```bash
zilliz stage apply --stage-name <stage-name>
# Optional:
#   --project-id <project-id>
#   --region-id <region-id>
#   --cluster-id <target-cluster-id>
#   --path <stage-subpath>
```

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

## Stages vs. Direct Integrations

A **stage** is a named, project-scoped handle to a pre-uploaded set of files in
managed cloud storage. Import jobs reference either:

- a customer-owned bucket via an integration (the original flow above), or
- a stage (`zilliz stage create --project-id <id> --region-id <region> --stage-name <name>`), which is preferable when the user wants Zilliz Cloud to host the staging bucket.

`stage apply` updates an existing stage in place; `stage delete` removes it
(confirm with the user first -- pending import jobs referencing the stage
will fail).

## Import Targets

`import start`, `import list`, and `import status` accept either:

- `--cluster-id <id>` (legacy form, still supported), or
- `--project-id <id>` together with `--region-id <region>` (the server then
  resolves the target instance from the project + region pair).

You must supply exactly one of those two grouping forms -- the CLI rejects
an import command that provides neither, or that provides `--project-id`
without `--region-id`.

## Guidance

- Import jobs run asynchronously. After starting a job, use `import status` to track progress.
- The data files must be accessible from Zilliz Cloud (either via a configured integration or via a stage).
- The collection schema must match the data file structure.
- When importing into a Vector Lake / on-demand-cluster setup, prefer the `--project-id` + `--region-id` form -- on-demand clusters do not have a stable single cluster ID to point at.

View saved version →

---
name: index
description: Use when the user wants to create, list, describe, or drop indexes on Milvus collections.
---

## Prerequisites

1. CLI installed, a usable data-plane credential configured, 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>
```

Before dropping an index, describe the affected collection and index, then obtain explicit user confirmation.

## 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.
- Before dropping an index, obtain explicit user confirmation because search availability may be affected.

View saved version →

---
name: job
description: Use when the user wants to check the status of an async Cloud Job (backup, restore, migration, import, or clone). Also use when the user wants to wait for a long-running operation to complete.
---

## Prerequisites

1. CLI installed and logged in (see setup skill).
2. A job ID from a previous async operation (backup create, import start, etc.).

## Commands Reference

### Describe a Job

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

## Wait for Completion

The `job describe` command supports a `--wait` flag to poll until the job finishes:

```bash
# Poll until done (default: 5s interval, 30min timeout)
zilliz job describe --job-id <job-id> --wait

# Custom timeout and interval
zilliz job describe --job-id <job-id> --wait --timeout 600 --interval 10
```

## Job Types

| Type             | Triggered By                                          |
| ---------------- | ----------------------------------------------------- |
| BACKUP           | `backup create`                                       |
| RESTORE          | `backup restore-cluster`, `backup restore-collection` |
| IMPORT           | `import start`                                        |
| MIGRATION        | Cloud migration operations                            |
| CLONE_COLLECTION | Collection clone operations                           |

## Job Statuses

| Status      | Meaning                           |
| ----------- | --------------------------------- |
| PENDING     | Job is queued                     |
| IN_PROGRESS | Job is running                    |
| SUCCESSFUL  | Job completed successfully        |
| FAILED      | Job failed (check `reason` field) |
| CANCELING   | Job is being cancelled            |
| CANCELED    | Job was cancelled                 |

## Guidance

- Many control-plane operations are **asynchronous** and return a `jobId`. Suggest using `job describe` to track progress.
- When a job fails, the `reason` field contains the error message. Display it to the user.
- For long-running operations (cluster creation, data migration), suggest using `--wait` so the user doesn't have to poll manually.
- The `--wait` flag shows a live progress spinner. Users can press Ctrl+C to stop waiting without cancelling the job itself.

View saved version →

---
name: monitoring
description: Use when the user wants to check cluster status, collection statistics, load states, or get an overview of their Zilliz Cloud resources.
---

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

### Time-series Metrics

For cluster-wide time series (CU sizing, storage, serverless VCU, slow queries) use `zilliz cluster metrics`:

```bash
zilliz cluster metrics --cluster-id <cluster-id> -m CU_COMPUTATION --period 1h
```

For per-collection time series (QPS, latency, entity counts, hybrid-search aliases) use `zilliz collection metrics` -- see the collection skill for metric scope rules and the full alias list:

```bash
zilliz collection metrics -c <collection-name> -m SEARCH_QPS --period 1h
```

Both commands render an inline Braille line chart by default (one block per metric with a `min / max / avg / last` summary). Pass an explicit `-o table` (or `--output table`) for the pivot-table layout, or use `-o json` / `--query` to get raw data for scripting.

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

View saved version →

---
name: on-demand-cluster
description: Use when the user wants to create, list, describe, or delete an on-demand (Vector Lake / VectorLake) cluster. On-demand clusters auto-suspend after an idle TTL and are intended for ad-hoc query workloads against a Vector Lake.
---

## Prerequisites

1. CLI installed and logged in (see setup skill).
2. A Vector Lake instance in the target project/region (see cluster
   skill -- `cluster create-vectorlake`).

## Commands Reference

### Create an On-Demand Cluster

`create` is hand-written and not generated from the JSON model. It calls
`POST /v2/clusters/createOnDemandCluster` and accepts:

```bash
zilliz on-demand-cluster create \
  --project-id <project-id> \
  --region-id <region-id> \
  --cu-size <integer>            # required, >= 8
  --cluster-name <string> \      # required, max 64 chars, letters/digits/space/_/-/CJK
  [--session-ttl <duration>] \   # auto-suspend TTL: 30m, 1h, 90s (min 60s, default 60s)
  [--max-query-node-cu <n>] \
  [--max-query-node-replicas <n>]
```

Session TTL controls how long an idle on-demand cluster stays running before
it is automatically suspended. Format is `<number><s|m|h>`, with a floor of
60 seconds. Resuming a suspended on-demand cluster happens transparently on
the next query.

Examples:

```bash
# Create an 8-CU on-demand cluster with the default 60s idle TTL
zilliz on-demand-cluster create \
  --project-id proj-xxxx \
  --region-id aws-us-east-1 \
  --cu-size 8 \
  --cluster-name "qc-prod-1"

# Keep alive 30 minutes between queries, cap query node CU and replicas
zilliz on-demand-cluster create \
  --project-id proj-xxxx \
  --region-id aws-us-east-1 \
  --cu-size 16 \
  --cluster-name "qc-batch-1" \
  --session-ttl 30m \
  --max-query-node-cu 16 \
  --max-query-node-replicas 4
```

### List On Demand Clusters

```bash
zilliz on-demand-cluster list --project-id <project-id> --region-id <cloud-region>
```

### Describe an On Demand Cluster

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

### Delete an On Demand Cluster

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

## Guidance

- On-demand clusters belong to a Vector Lake instance and only exist inside a `<projectId>` + `<regionId>` pair. If neither `list` nor `describe` returns anything, first confirm that the project has a Vector Lake (`zilliz cluster create-vectorlake`).
- `list` requires both `--project-id` and `--region-id` -- there is no all-projects listing.
- Status flows through `CREATING` -> `RUNNING` -> `SUSPENDING` -> `SUSPENDED` and back to `RESUMING` -> `RUNNING` on the next query. Treat `SUSPENDING`/`SUSPENDED` as healthy idle state, not an error.
- `--session-ttl` is the idle auto-suspend timer. The minimum is `60s`; values smaller than that are rejected client-side before the API call. The current default is `60s`, so on-demand clusters are aggressive about suspending -- raise it (e.g. `30m`) when running interactive workloads.
- `--cu-size` must be >= 8 and `--cluster-name` is at most 64 characters, allowing letters, digits, space, `_`, `-`, and Chinese characters.
- `delete` is irreversible and asynchronous -- always confirm with the user before invoking. The cluster row moves to `DELETING` and disappears once cleanup finishes.
- These commands are distinct from the regular `cluster` skill: a regular cluster owns its own compute, while on-demand clusters share storage with their parent Vector Lake. Do not confuse `zilliz on-demand-cluster delete` with `zilliz cluster delete`.

View saved version →

---
name: partition
description: Use when the user wants to create, list, load, release, or drop partitions in a Milvus collection.
---

## Prerequisites

1. CLI installed, a usable data-plane credential configured, 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.

View saved version →

---
name: privatelink
description: Use when the user wants to list available PrivateLink endpoint services, list/create/delete PrivateLink endpoints for a project, or manage the endpoint whitelist on Zilliz Cloud.
---

## Prerequisites

1. CLI installed and logged in (see setup skill).
2. A project to attach endpoints to (see project-region skill).

## Commands Reference

### List available PrivateLink endpoint services

```bash
zilliz privatelink list-services
# Optional: --region-id <filter-by-cloud-region>
```

### List Privatelinks

```bash
zilliz privatelink list --project-id <project-id>
```

### Create a Privatelink

```bash
zilliz privatelink create \
  --project-id <project-id> \
  --region-id <cloud-region> \
  --endpoint-id <vpc-endpoint-id>
# Optional: --gcp-project-id <gcp-project-id>
```

### Delete a Privatelink

```bash
zilliz privatelink delete --project-id <project-id> --endpoint-id <endpoint-id-to-delete>
```

### Add region to PrivateLink endpoint whitelist

```bash
zilliz privatelink add-whitelist --project-id <project-id> --region-id <cloud-region-to-whitelist>
```

## Guidance

- PrivateLink lets a cluster be reached over a cloud-provider private network (AWS PrivateLink, GCP Private Service Connect, Azure Private Link) instead of the public internet. Endpoints are scoped to a project and a region.
- Workflow for a new endpoint:
  1. `zilliz privatelink list-services --region-id <region>` to find the `endpointService` value for that region (and whether `whitelistRequired` is true).
  2. If `whitelistRequired` is true, call `zilliz privatelink add-whitelist --project-id <id> --region-id <region>` first so the project is allowed to attach an endpoint in that region.
  3. Create the VPC endpoint in your own cloud account (out-of-band, in the AWS/GCP/Azure console or via IaC) and capture its endpoint ID (e.g. `vpce-xxxx`).
  4. Register it with `zilliz privatelink create --project-id <id> --region-id <region> --endpoint-id <vpce-id>`. For GCP, also pass `--gcp-project-id <gcp-project>`.
- `list` is per-project: `zilliz privatelink list --project-id <id>`. There is no global listing.
- `delete` is irreversible -- always confirm with the user, especially in production. Existing connections from that endpoint stop working immediately.
- After enabling PrivateLink for a cluster, the cluster's endpoint URL switches to the private DNS form. Re-run `zilliz cluster describe --cluster-id <id>` to fetch the updated endpoint and update any consumer config.

View saved version →

---
name: project-region
description: Use when the user wants to manage Zilliz Cloud projects or storage volumes. For cloud regions and providers, see the cluster skill.
---

## Prerequisites

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

## Commands Reference

### Projects

#### Create a Project

```bash
zilliz project create --name <project-name> --plan <Standard|Enterprise|BusinessCritical>
# Optional: --region '[...]'
```

#### List Projects

```bash
zilliz project list
```

#### Describe a Project

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

#### Delete a Project

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

Before deleting a project, describe the affected project and obtain explicit user confirmation. Project deletion can affect every resource in that project.

#### Upgrade a Project

```bash
zilliz project upgrade --project-id <project-id> --plan <Standard|Enterprise|BusinessCritical>
```

#### Bind additional regions to an existing project

```bash
zilliz project add-regions --project-id <project-id> --region '[...]'
```

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

#### Describe a Volume

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

#### Apply

```bash
zilliz volume apply --name <volume-name>
# Optional: --project-id <project-id>
```

## 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 project or volume, describe the affected resource and obtain explicit user confirmation.

View saved version →

---
name: quickstart
description: Use when the user wants to set up, install, authenticate, or configure the Zilliz Cloud CLI and cluster context for the first time (one-shot onboarding).
---

Guide the user through the complete Zilliz Cloud CLI setup. Follow these steps in order:

## Step 1: Install zilliz-cli

Check if already installed:

```bash
zilliz --version
```

If not installed or needs upgrading:

```bash
curl -fsSL https://raw.githubusercontent.com/zilliztech/zilliz-cli/master/install.sh | bash
```

Verify:

```bash
zilliz --version
```

## Step 2: Inspect available access

Inspect control-plane authentication and the existing data-plane context independently:

```bash
zilliz auth status
zilliz context current --output json
```

If the requested workflow needs control-plane access and no usable authentication is available, instruct the user to open their own terminal and run one of:

1. **Browser login** — `zilliz login` — opens a browser for OAuth and uses the account's assigned permissions.
2. **API Key via login** — `zilliz login --api-key` — prompts for API key, no browser needed.
3. **API Key via configure (legacy)** — `zilliz configure` — prompts for API key, simpler setup.
4. **Environment variable** — configure `ZILLIZ_API_KEY` with a token supported by the intended API endpoint.

**IMPORTANT:** These commands require interactive input and cannot run inside the agent. Do NOT ask the user to paste API keys into the chat.

Do not require `zilliz auth status` to succeed for a data-plane-only workflow. If an endpoint and context are already available, validate them with `zilliz database list --output json` or `zilliz collection list --output json`.

## Step 3: Resolve the target context

When control-plane discovery is available, list clusters:

```bash
zilliz cluster list --output json
```

If discovery is unavailable, ask the user to configure the cluster ID and endpoint in their own terminal. Set an explicit context instead of treating discovery failure as an authentication failure:

```bash
zilliz context set --cluster-id <cluster-id> --endpoint <endpoint>
zilliz database list --output json
zilliz context set --database <database-name>
```

Use a database returned by the service or an existing database already stored in context. Do not assume its name.

## Step 4: Verify the requested capability

Confirm the data-plane context and perform a non-destructive probe:

```bash
zilliz context current --output json
zilliz collection list --output json
```

If the user also needs control-plane operations, verify the relevant read command separately. Report which capabilities were verified and which were unavailable without inferring the reason from a service label alone.

View saved version →

---
name: setup
description: Use when the user needs to install zilliz-cli, log in to Zilliz Cloud, configure credentials, or set the active cluster context. Also use when any other skill reports a missing prerequisite.
---

## Setup approach

Treat control-plane authentication and data-plane access as separate capabilities. Do not require one as proof of the other.

1. Check whether the CLI is installed with `zilliz --version`.
2. Inspect the current control-plane authentication state with `zilliz auth status`.
3. Inspect the current data-plane context with `zilliz context current --output json`.
4. Validate the capability needed for the user's task with a non-destructive command. For example, use `zilliz cluster list --output json` for control-plane discovery or `zilliz database list --output json` / `zilliz collection list --output json` for data-plane access.

A failed control-plane authentication check does not prove that an explicitly configured data-plane credential is invalid. Continue with the available context and validate the requested operation directly.

## Commands Reference

### Install / Upgrade CLI

```bash
curl -fsSL https://raw.githubusercontent.com/zilliztech/zilliz-cli/master/install.sh | bash
```

Verify installation:

```bash
zilliz --version
```

### Authentication

Interactive login and credential configuration must happen in the user's own terminal, not in a non-interactive agent shell.

Check if already logged in:

```bash
zilliz auth status
```

If the task needs control-plane access and no usable authentication is available, tell the user to open their own terminal and run one of the following:

**Option 1: Browser-based login (OAuth)**

```
zilliz login
```

- Opens a browser for authentication
- Uses the signed-in account's assigned control-plane permissions
- 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
  - Available control-plane operations depend on the key's assigned permissions

**Option 3: Environment variable**

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

```
export ZILLIZ_API_KEY=<your-api-key>
```

The environment variable can also carry a data-plane token supported by the target endpoint. Never ask the user to paste the value into the conversation.

After the user completes control-plane authentication, verify it with:

```bash
zilliz auth status
```

For data-plane-only access, verify the endpoint, database, and credential with a non-destructive data command instead of requiring `zilliz auth status` to succeed.

### 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 when endpoint discovery is available
zilliz context set --cluster-id <cluster-id>

# Set an explicit data-plane context when discovery is unavailable
zilliz context set --cluster-id <cluster-id> --endpoint <url> --database <database-name>

# Change the active database
zilliz context set --database <db-name>
```

Do not assume a database name. Prefer the database already stored in the context; otherwise run `zilliz database list --output json` and use a database returned by the service.

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

## Capability detection

Available operations can vary with the credential, endpoint, service configuration, and current context. Prefer direct, non-destructive capability checks over inferring behavior from a cluster label.

- For control-plane tasks, test the narrowest relevant read command first.
- For data-plane tasks, confirm the explicit endpoint and database, then test `database list` or `collection list`.
- If a command is unavailable or denied, report the returned error and continue with independent capabilities when possible.
- Do not turn a failed optional check, such as cluster discovery or cluster metadata lookup, into a blocker for an otherwise working data-plane task.

## Troubleshooting

- **"command not found" after install:** Check that the install directory (e.g., `~/.local/bin`) is in your PATH. Try re-running the install script: `curl -fsSL https://raw.githubusercontent.com/zilliztech/zilliz-cli/master/install.sh | bash`.
- **Control-plane "not authenticated" errors:** Run `zilliz auth status`. If the task is data-plane-only, validate the configured endpoint and database separately before asking the user to log in again.
- **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:** Preserve the server or CLI error, verify the target endpoint and database, and explain that the current credential or service configuration does not expose that operation.
- **Network or timeout errors:** Verify the endpoint and retry a non-destructive operation once. If control-plane metadata is available, use it as additional evidence rather than a mandatory prerequisite.

## Guidance

- Validate only the capabilities needed for the current task.
- Treat control-plane discovery and data-plane operations as independent when the available credentials support only one of them.
- NEVER run `zilliz login`, `zilliz configure`, or `zilliz auth switch` (without arguments) inside a non-interactive agent shell — 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 setup is complete, verify the narrowest capability needed for the requested task.
- After setting context, verify with `zilliz context current`.
- For data-plane commands in other skills, verify that context includes the intended endpoint and database.
- When a command fails unexpectedly, verify the endpoint, database, credential scope, and current context before drawing conclusions about service support.

View saved version →

---
name: status
description: Use when the user wants a comprehensive overview of their current Zilliz Cloud environment — context, cluster details, databases, and collections with stats.
---

Gather and display a status overview of the user's current Zilliz Cloud environment. Run commands with `--output json` for structured data, then present a formatted summary.

## Step 1: Inspect current access

Verify the CLI and inspect both authentication surfaces:

```bash
zilliz --version
zilliz auth status
zilliz context current --output json
```

Do not stop solely because `zilliz auth status` reports no control-plane login. A configured data-plane context may still be usable.

## Step 2: Show Current Context

```bash
zilliz context current --output json
```

If no context is set, suggest running `zilliz context set --cluster-id <id>`.

## Step 3: Optional cluster details

Using the cluster ID from context:

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

If this command succeeds, present the cluster name, status, plan, and region. If it is unavailable or denied, preserve the error briefly and continue with data-plane status. Do not ask the user to change credentials unless cluster metadata is required for their request.

## Step 4: Database List

```bash
zilliz database list --output json
```

If database listing is unavailable but the context already names a database, continue with that database and mark database discovery as unavailable.

## Step 5: Collections Summary

For each database returned in Step 4, gather collection information:

```bash
zilliz collection list --database <db-name> --output json
```

For each collection, gather stats and index info:

```bash
zilliz collection get-stats --name <name> --database <db-name> --output json
zilliz collection get-load-state --name <name> --database <db-name> --output json
zilliz index list --collection <name> --database <db-name> --output json
```

## Step 6: Present Summary

Format the results as a readable summary:

**Context:** <cluster-id> | <endpoint>
**Cluster metadata:** <available fields, or unavailable with the current access>

For each database, show its collections:

**Database:** <db-name>

| Collection | Rows | Load State | Indexes |
|---|---|---|---|
| my_collection | 10,000 | Loaded | vector_idx (AUTOINDEX) |
| ... | ... | ... | ... |

Distinguish verified facts from unavailable metadata. Report successful data-plane checks even when optional control-plane checks fail.

View saved version →

---
name: user-role
description: Use when the user wants to manage database users, roles, passwords, or access privileges in Milvus.
---

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

*Create a new database user.*

#### List Users

```bash
zilliz user list
```

*List all database users.*

#### Describe a User

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

*Get details of a user.*

#### Drop a User

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

*Drop a database user.*

#### Update Password

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

*Update user password.*

#### Grant a Role to a User

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

*Grant a role to a user.*

#### Revoke a Role from a User

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

*Revoke a role from a user.*

### Roles

#### Create a Role

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

*Create a new role.*

#### List Roles

```bash
zilliz role list
```

*List all roles.*

#### Describe a Role

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

*Get details and privileges of a role.*

#### Drop a Role

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

*Drop a role.*

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

*Grant a privilege to a role.*

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

*Revoke a privilege from a role.*

## Common Privileges

Common privileges by object type:

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

## Guidance

- Never ask the user to paste a password or API key into the conversation. Present password-bearing commands with placeholders and instruct the user to run them in their own terminal.
- 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.

View saved version →

---
name: vector
description: Use when the user wants to search, query, insert, upsert, get, or delete vectors in a Milvus collection.
---

## Prerequisites

1. CLI installed, a usable data-plane credential configured, 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>
```

Before deleting vectors, show the target collection and filter, explain that matching data will be removed, and obtain explicit user confirmation.

## 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.
- Before deleting vectors, resolve the exact collection and filter and obtain explicit user confirmation.