Metadata-Version: 2.4
Name: zilliz-cli
Version: 1.0.0
Summary: CLI for Zilliz Cloud resource management and Milvus operations
Project-URL: Homepage, https://zilliz.com
Project-URL: Documentation, https://docs.zilliz.com
Author-email: Zilliz <support@zilliz.com>
License-Expression: Apache-2.0
Keywords: cli,milvus,vector-database,zilliz
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: jmespath>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# Zilliz CLI

The official command-line tool for [Zilliz Cloud](https://zilliz.com) cluster management and [Milvus](https://milvus.io) 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. Login or configure API Key
zilliz login
# or
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
```

## Command Reference

For detailed command documentation with all options and examples, see the [Command Reference](docs/command-reference.md).

### Cloud Management

| Command | Subcommand | Description |
|---------|-----------|-------------|
| `cluster` | `list` | List all clusters |
| | `describe` | Get details of a cluster |
| | `create` | Create a new cluster |
| | `modify` | Modify cluster configuration (scale CU or replicas) |
| | `suspend` | Suspend a running cluster |
| | `resume` | Resume a suspended cluster |
| | `delete` | Delete a cluster |
| | `providers` | List all cloud providers (aws, gcp, azure) |
| | `regions` | List available regions for a cloud provider |
| | `metrics` | Query cluster performance metrics (QPS, latency, storage, etc.) |
| `project` | `list` | List all projects |
| | `describe` | Get details of a project |
| | `create` | Create a new project |
| | `upgrade` | Upgrade project plan |
| `backup` | `list` | List all backups |
| | `describe` | Get details of a backup |
| | `create` | Create a backup for a cluster |
| | `delete` | Delete a backup |
| | `export` | Export a backup to external storage |
| | `restore-cluster` | Restore a backup to a new cluster |
| | `restore-collection` | Restore specific collections from a backup |
| | `describe-policy` | Describe backup policy for a cluster |
| | `update-policy` | Update backup policy for a cluster |
| `volume` | `list` | List all volumes in a project |
| | `create` | Create a new volume |
| | `delete` | Delete a volume |
| `import` | `start` | Start a data import job |
| | `list` | List import jobs for a cluster |
| | `status` | Get status of an import job |
| `billing` | `usage` | Query usage costs for a time range |
| | `invoices` | List invoices, or get details of a specific invoice |
| | `bind-card` | Bind a credit card to your account |
| `job` | `describe` | Get status of an async job (backup, restore, import, etc.) |
| `alert` | `list` | List alert rules for a project |
| | `create` | Create a new alert rule |
| | `update` | Update an existing alert rule |
| | `delete` | Delete an alert rule |
| | `enable` | Enable an alert rule |
| | `disable` | Disable an alert rule |

### Data Operations

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

| Command | Subcommand | Description |
|---------|-----------|-------------|
| `collection` | `list` | List all collections |
| | `describe` | Get details of a collection |
| | `create` | Create a new collection |
| | `drop` | Drop a collection |
| | `rename` | Rename a collection |
| | `load` | Load a collection into memory for search |
| | `release` | Release a collection from memory |
| | `get-load-state` | Get collection load state |
| | `get-stats` | Get collection statistics (row count, etc.) |
| | `has` | Check if a collection exists |
| | `flush` | Flush collection data to disk |
| | `compact` | Compact collection segments to optimize storage |
| `vector` | `search` | Search for similar vectors |
| | `hybrid-search` | Perform hybrid search with multiple vectors and reranking |
| | `query` | Query entities by scalar filter expression |
| | `get` | Get entities by primary key IDs |
| | `insert` | Insert entities into a collection |
| | `upsert` | Upsert entities (insert or update if exists) |
| | `delete` | Delete entities by filter expression |
| `index` | `list` | List indexes on a collection |
| | `describe` | Get details of an index |
| | `create` | Create an index on a collection field |
| | `drop` | Drop an index |
| `partition` | `list` | List partitions in a collection |
| | `create` | Create a partition in a collection |
| | `drop` | Drop a partition |
| | `has` | Check if a partition exists |
| | `get-stats` | Get partition statistics |
| | `load` | Load partitions into memory |
| | `release` | Release partitions from memory |
| `database` | `list` | List all databases |
| | `describe` | Get details of a database |
| | `create` | Create a new database |
| | `drop` | Drop a database |
| `user` | `list` | List all database users |
| | `describe` | Get details of a user |
| | `create` | Create a new database user |
| | `drop` | Drop a database user |
| | `update-password` | Update user password |
| | `grant-role` | Grant a role to a user |
| | `revoke-role` | Revoke a role from a user |
| `role` | `list` | List all roles |
| | `describe` | Get details and privileges of a role |
| | `create` | Create a new role |
| | `drop` | Drop a role |
| | `grant-privilege` | Grant a privilege to a role |
| | `revoke-privilege` | Revoke a privilege from a role |
| `alias` | `list` | List all aliases |
| | `describe` | Get details of an alias |
| | `create` | Create an alias pointing to a collection |
| | `alter` | Reassign an alias to another collection |
| | `drop` | Drop an alias |

### Configuration

| Command | Subcommand | Description |
|---------|-----------|-------------|
| `login` | | Log in to Zilliz Cloud (browser OAuth or API key) |
| `logout` | | Log out and clear stored credentials |
| `auth` | `status` | Show current authentication status |
| | `switch` | Switch to a different organization |
| `configure` | *(interactive)* | Interactive API key setup |
| | `set` | Set a configuration value |
| | `get` | Get a configuration value |
| | `list` | List all configuration values |
| | `clear` | Clear all stored credentials |
| `context` | `set` | Set the current cluster context |
| | `current` | Show the current context |
| `completion` | `install` | Install shell completion |
| | `show` | Show the completion script |
| | `status` | Check if shell completion is installed |
| | `uninstall` | Remove shell completion from RC file |
| `version` | | Show CLI version |

## Usage Examples

### Authentication

```bash
# Browser-based login (recommended)
zilliz login

# Login with API key (for CI/CD or non-interactive environments)
zilliz login --api-key

# Check login status
zilliz auth status

# Switch organization
zilliz auth switch
```

### Cluster Management

```bash
# List all clusters
zilliz cluster list
zilliz cluster list -o 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
```

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

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

# View current context
zilliz context current
zilliz context current -o json
```

### Collection Operations

```bash
# List collections
zilliz collection list

# Describe a collection
zilliz collection describe --name my_collection

# Quick create with defaults
zilliz collection create --name my_collection --dimension 768 --metric-type COSINE

# Create with full JSON schema (supports file://)
zilliz collection create --name my_col --body file://schema.json

# Drop a collection
zilliz collection drop --name my_collection
```

### Vector Operations

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

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

# Insert data (from file)
zilliz vector insert --collection my_col --data file://data.json
zilliz vector insert --collection my_col --body file://insert_body.json

# Hybrid search (from file)
zilliz vector hybrid-search --collection my_col --body file://hybrid-search.json
```

### Backup & Restore

```bash
# Create a backup
zilliz backup create --cluster-id in01-xxxx

# List backups
zilliz backup list --cluster-id in01-xxxx

# Restore to a new cluster
zilliz backup restore-cluster --backup-id backup-xxxx --project-id p1 --region aws-us-west-2
```

### Billing

```bash
# View today's usage
zilliz billing usage

# View usage for last 7 days
zilliz billing usage --duration 7d

# List invoices
zilliz billing invoices
```

## Global Options

| Option | Description |
|--------|-------------|
| `--output`, `-o` | Output format: `json`, `table`, `text`, `yaml`, `csv` |
| `--query` | Filter output with JMESPath expression |
| `--no-header` | Omit table headers (useful for scripting) |
| `--api-key` | API key (overrides config file and env var) |
| `--version` | Show the version and exit |
| `--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 and login data
  config          # CLI settings + cluster context
```

## Output Formats

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

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

# Plain text
zilliz cluster list -o text

# YAML
zilliz cluster list -o yaml

# CSV
zilliz cluster list -o csv

# Filter output with JMESPath
zilliz cluster list -o json --query "[].{name: clusterName, status: status}"
```

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