# zilliz
A unified CLI and TUI (Terminal User Interface) for managing Zilliz Cloud clusters and Milvus vector database operations, written in Rust.
## Features
- **Dual interface** -- interactive TUI mode and traditional CLI commands
- **Model-driven** -- operations defined in JSON, supporting dynamic command generation
- **Multi-resource management** -- clusters, collections, vectors, indexes, backups, billing, and more
- **Rich output** -- table, JSON, YAML, CSV, and text formats with JMESPath filtering
- **Async job polling** -- `--wait` flag for long-running operations
- **Metrics** -- query cluster and collection metrics; default output is an inline Braille line chart per metric with `min / max / avg / last` summary (pass `-o table` for the pivot-table layout, `-o json` / `--query` for raw data)
## Quick Start
### Install
```bash
cargo install zilliz
```
This installs two binaries: `zilliz` (primary) and `zz` (shorthand alias). Both are identical.
### Uninstall
```bash
zilliz uninstall # remove the binary and `zz` alias; preserves ~/.zilliz/
zilliz uninstall --purge # also remove ~/.zilliz/ (credentials, config)
zilliz uninstall --yes # skip the confirmation prompt
```
If you installed via `cargo install zilliz`, also run `cargo uninstall zilliz`
afterwards to clear Cargo's registry record.
### Updating
Once installed, update in place by re-running the installer:
```bash
zilliz upgrade # confirms and re-runs the official installer
zilliz upgrade --check # only report whether a newer version exists
zilliz upgrade --yes # skip the confirmation prompt
```
`update` is an accepted alias (`zilliz update`).
### Guided onboarding
If this is your first time, run:
```bash
zilliz quickstart
```
It walks you through sign-in, picks an organization and cluster, lets you
run a few common commands interactively, and prints a copy-pasteable
cheatsheet of next-step commands. Use `zilliz quickstart --non-interactive`
(or pipe the output) to print the cheatsheet only — handy in scripts or CI.
### Authenticate
```bash
# Browser-based OAuth (recommended)
zilliz login
# Login with an API key (prompted if no value is given)
zilliz login --api-key
zilliz login --api-key sk-xxx
# Log in to the CN cloud (api.cloud.zilliz.com.cn) — API key only
zilliz login --cn
zilliz login --cn --api-key sk-xxx
# Or configure credentials interactively
zilliz configure
```
### Set Cluster Context
A cluster context is required for data-plane operations (collections, vectors, etc.).
```bash
# Interactive selection
zilliz context set
# Or specify directly
zilliz context set --cluster-id <id>
# Check current context
zilliz context current
```
### Launch TUI
```bash
zilliz
```
Running `zilliz` without arguments starts the interactive terminal UI.
### Use CLI
```bash
# List clusters
zilliz cluster list
# Describe a collection (using shorthand alias)
zilliz collection describe
# JSON output with JMESPath filtering
zilliz cluster list -o json --query "clusters[*].{id:clusterId,name:clusterName}"
# Suppress table headers
zilliz cluster list --no-header
# Wait for an async operation to complete
zilliz cluster create --wait
```
## CLI Commands
### Built-in Commands
| `login` | Log in to Zilliz Cloud (OAuth, `--api-key`, or `--cn` for CN cloud) |
| `logout` | Log out and clear stored credentials |
| `configure` | Manage configuration (`set`, `get`, `list`, `clear`) |
| `context` | Manage cluster context (`set`, `current`, `clear`) |
| `auth status` | Show current authentication status |
| `auth switch` | Switch to a different organization |
| `completion` | Shell completions (`install`, `uninstall`, `status`, `show`) |
| `version` | Display version info |
### Control-Plane Commands (Cloud Management)
| `cluster` | `list`, `describe`, `modify`, `suspend`, `resume`, `delete`, `create`, `providers`, `regions`, `metrics` |
| `project` | `create`, `list`, `describe`, `upgrade` |
| `backup` | `create`, `list`, `describe`, `delete`, `export`, `restore-cluster`, `restore-collection`, `describe-policy`, `update-policy` |
| `import` | `start`, `list`, `status` |
| `volume` | `create`, `list`, `delete` |
| `job` | `describe` |
| `billing` | `usage`, `invoices` |
### Data-Plane Commands (Milvus Operations)
These commands require a cluster context (`zilliz context set`).
| `collection` | `create`, `list`, `describe`, `drop`, `rename`, `load`, `release`, `get-load-state`, `get-stats`, `has`, `flush`, `compact`, `metrics` |
| `vector` | `insert`, `upsert`, `search`, `hybrid-search`, `query`, `get`, `delete` |
| `database` | `create`\*, `list`, `describe`\*, `drop`\* |
| `index` | `create`, `list`, `describe`, `drop` |
| `partition` | `create`, `list`, `drop`, `has`, `get-stats`, `load`, `release` |
| `user` | `create`\*, `list`\*, `describe`\*, `drop`\*, `update-password`\*, `grant-role`\*, `revoke-role`\* |
| `role` | `create`\*, `list`\*, `describe`\*, `drop`\*, `grant-privilege`\*, `revoke-privilege`\* |
| `alias` | `create`, `list`, `describe`, `alter`, `drop` |
| `external-collection refresh` | `trigger`, `describe`, `list` |
\* Dedicated clusters only.
### Local Milvus Standalone
Manage a local Milvus standalone Docker deployment via the official
[`standalone_embed.sh`](https://milvus.io/docs/install_standalone-docker.md)
script. Requires `bash` and a working Docker daemon (macOS / Linux / WSL).
| `zilliz milvus standalone install` | Download `standalone_embed.sh` into `./milvus-standalone` (or `--dir <path>`). |
| `zilliz milvus standalone start` | Run `bash standalone_embed.sh start`. |
| `zilliz milvus standalone stop` | Run `bash standalone_embed.sh stop`. |
| `zilliz milvus standalone restart` | Stop and start the container. |
| `zilliz milvus standalone delete` | Remove container, `volumes/`, and config files (destructive — prompts for confirmation, or pass `--yes`). |
| `zilliz milvus standalone upgrade` | Replace `standalone_embed.sh` with the latest from upstream master and restart (destructive — prompts, or pass `--yes`). Alias: `update`. |
Common flags: `--dir <path>`, `--dry-run`, `-y / --yes`, `-h / --help`. Install
also accepts `--script-url <https://...>`, `--start`, and `--force`.
```bash
# Preview without touching the filesystem or Docker
zilliz milvus standalone install --dry-run
# Install and start in one go
zilliz milvus standalone install --start
# Manage the running deployment
zilliz milvus standalone stop
zilliz milvus standalone restart
zilliz milvus standalone upgrade --yes
zilliz milvus standalone delete --yes
```
Default endpoints after start: Milvus `localhost:19530`, WebUI
`http://localhost:9091`, embedded etcd `localhost:2379`. Data is persisted
under `<install-dir>/volumes/milvus`.
### Global Flags
| `--api-key <KEY>` | Override API key (or set `ZILLIZ_API_KEY` env var) |
| `-o, --output <FMT>` | Output format: `table` (default), `json`, `yaml`, `csv`, `text` |
| `-a, --all` | Fetch all pages for paginated responses |
| `--query <JMESPATH>` | Filter output with a JMESPath expression |
| `--no-header` | Suppress table/CSV header row |
| `--wait` | Wait for async jobs to reach a terminal state |
## TUI Keyboard Shortcuts
| `q` / `Esc` | Quit |
| `Ctrl+C` | Force quit |
## Configuration
Config files are stored in `~/.zilliz/` (compatible with zilliz-cli):
| `credentials` | API keys, user info, org data (INI format) |
| `config` | Cluster context and database preferences (INI format) |
### Environment Variables
| `ZILLIZ_CONFIG_DIR` | Override config directory (default: `~/.zilliz/`) |
| `ZILLIZ_API_KEY` | Set API key (overrides config file) |
| `RUST_LOG` | Enable debug logging (e.g., `RUST_LOG=zilliz=debug`) |
## Tech Stack
- [ratatui](https://github.com/ratatui/ratatui) -- terminal UI framework
- [clap](https://github.com/clap-rs/clap) -- CLI argument parsing
- [tokio](https://github.com/tokio-rs/tokio) -- async runtime
- [reqwest](https://github.com/seanmonstar/reqwest) -- HTTP client