zilliz-cloud

What this skill does

# Zilliz Cloud CLI Skill

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

## When to Use

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

## Capabilities Overview

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

## Requirements

- Python 3.10+
- A [Zilliz Cloud](https://cloud.zilliz.com/) account (or local Milvus instance)

---

# Setup & Authentication

## Prerequisites

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

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

## Install / Upgrade CLI

```bash
python3 -m pip install --upgrade zilliz-cli
```

Verify installation:

```bash
zilliz --version
```

## Authentication

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

Check if already logged in:

```bash
zilliz auth status
```

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

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

```
zilliz login
```

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

**Option 2a: API Key via login command**

```
zilliz login --api-key
```

**Option 2b: API Key via configure (legacy)**

```
zilliz configure
```

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

**Option 3: Environment variable**

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

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

After the user completes authentication, verify by running:

```bash
zilliz auth status
```

## Configure Subcommands

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

## Switch Organization

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

```
# Interactive selection
zilliz auth switch

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

## Logout

```bash
zilliz logout
```

## Set Cluster Context

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

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

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

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

## View Current Context

```bash
zilliz context current
```

## Output Format

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

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

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

## Cluster Type Differences

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

---

# Quickstart Command

Guide the user through the complete Zilliz Cloud CLI setup:

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

---

# Cluster Management

## List Clusters

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

## Describe a Cluster

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

## Create a Cluster

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

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

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

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

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

## Delete / Suspend / Resume a Cluster

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

## Modify a Cluster

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

### Cluster Guidance

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

---

# Collection Management

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

## List / Describe Collections

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

## Create a Collection

Quick create with auto schema:

```bash
zilliz collection create --name <name> --dimension <dim>
# Optional: --metric-type COSINE|L2|IP --id-ty