zilliz-cli 0.1.1
CLI for Zilliz Cloud resource management and Milvus operations
Requires Python: >=3.10
Keywords: cli, milvus, vector-database, zilliz

# Zilliz CLI

Command-line tool for Zilliz Cloud cluster management and Milvus vector database operations.

## Requirements

- Python 3.10+

## Installation

```bash
pip install zilliz-cli
```

For development (from source):

```bash
git clone git@github.com:zilliztech/zilliz-cloud.git
cd zilliz-cloud/vdc/zilliz-cli
pip install -e ".[dev]"
```

## Quick Start

```bash
# 1. Configure API Key
zilliz configure
# or
export ZILLIZ_API_KEY=your-api-key

# 2. List clusters
zilliz cluster list

# 3. Set cluster context (auto-resolves endpoint)
zilliz context set --cluster-id in01-xxxx

# 4. Work with collections and vectors
zilliz collection list
zilliz vector search --collection my_col --data '[[0.1, 0.2, 0.3]]' --limit 5
```

## Commands

### Configuration

```bash
# Interactive setup
zilliz configure

# Set individual values
zilliz configure set api_key YOUR_KEY
zilliz configure set output json

# View values
zilliz configure get api_key
zilliz configure list
```

### Context

```bash
# Set cluster context (endpoint auto-resolved)
zilliz context set --cluster-id in01-xxxx

# Set with specific database
zilliz context set --cluster-id in01-xxxx --database mydb

# Change database only
zilliz context set --database another_db

# Manual endpoint override
zilliz context set --cluster-id in01-xxxx --endpoint https://custom.endpoint.com

# View current context
zilliz context current
```

### Cluster Management

```bash
# List all clusters
zilliz cluster list
zilliz cluster list --output json

# Describe a cluster
zilliz cluster describe --cluster-id in01-xxxx

# Create a serverless cluster
zilliz cluster create --name my-cluster --project-id p1 --region gcp-us-west1

# Delete a cluster
zilliz cluster delete --cluster-id in01-xxxx
```

### Collection Operations

Requires a context to be set first (`zilliz context set --cluster-id ...`).

```bash
# List collections
zilliz collection list

# Describe a collection
zilliz collection describe --name my_collection

# Quick Setup: create with dimension and metric type
zilliz collection create --name my_collection --dimension 768 --metric-type COSINE

# Custom Setup: create with full JSON schema
zilliz collection create --body '{"collectionName": "my_col", "schema": {...}}'
zilliz collection create --body file://schema.json
```

### Vector Operations

Requires a context to be set first (`zilliz context set --cluster-id ...`).

```bash
# Vector search
zilliz vector search --collection my_col --data '[[0.1, 0.2, 0.3]]' --limit 10
zilliz vector search --collection my_col --data '[[0.1, 0.2, 0.3]]' --filter "age > 20" --output-fields '["name", "age"]'

# Query by filter
zilliz vector query --collection my_col --filter "id in [1, 2, 3]" --limit 10
zilliz vector query --collection my_col --filter "age > 20" --output-fields '["name", "age"]'

# Insert data
zilliz vector insert --collection my_col --data '[{"id": 1, "vector": [0.1, 0.2], "name": "doc1"}]'
```

### Version

```bash
zilliz version
zilliz version --output json
```

## Global Options

| Option | Description |
|--------|-------------|
| `--output`, `-o` | Output format: `json`, `table`, `text` |
| `--api-key` | API key (overrides config file and env var) |
| `--help` | Show help |

## Configuration

### Credential Resolution

API Key is resolved in order (first found wins):
1. `--api-key` CLI flag
2. `ZILLIZ_API_KEY` environment variable
3. `~/.zilliz/credentials` file

### Config Files

```
~/.zilliz/
  credentials     # API key
  config          # CLI settings + cluster context
```

## Output Formats

```bash
# Table (default, human-friendly)
zilliz cluster list

# JSON (machine/agent-friendly)
zilliz cluster list --output json

# Plain text
zilliz cluster list --output text
```

## Testing

```bash
# Run unit tests
pytest tests/unit/

# Run all tests (E2E tests skipped without API key)
pytest

# Run E2E tests (requires real API key)
ZILLIZ_API_KEY=your-key pytest -m e2e

# Run E2E tests with data plane (requires cluster)
ZILLIZ_API_KEY=your-key ZILLIZ_CLUSTER_ID=in01-xxxx pytest -m e2e
```

## License

Apache-2.0