{"id":19444,"plugin_id":"plugins_6a992fa57b6481918dffd35d23f03408","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:15:34.817Z","digest":"8ffe78a7315b383573e654ae93265eec57e0b4bf57ac6795e18a04b22d1889f0","against":null,"payload":{"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.","included_files":[],"name":"setup","skill_md_contents":"---\nname: setup\ndescription: 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.\n---\n\n## Setup approach\n\nTreat control-plane authentication and data-plane access as separate capabilities. Do not require one as proof of the other.\n\n1. Check whether the CLI is installed with `zilliz --version`.\n2. Inspect the current control-plane authentication state with `zilliz auth status`.\n3. Inspect the current data-plane context with `zilliz context current --output json`.\n4. 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.\n\nA 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.\n\n## Commands Reference\n\n### Install / Upgrade CLI\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/zilliztech/zilliz-cli/master/install.sh | bash\n```\n\nVerify installation:\n\n```bash\nzilliz --version\n```\n\n### Authentication\n\nInteractive login and credential configuration must happen in the user's own terminal, not in a non-interactive agent shell.\n\nCheck if already logged in:\n\n```bash\nzilliz auth status\n```\n\nIf 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:\n\n**Option 1: Browser-based login (OAuth)**\n\n```\nzilliz login\n```\n\n- Opens a browser for authentication\n- Uses the signed-in account's assigned control-plane permissions\n- Use `--no-browser` in headless environments (displays a URL to visit manually)\n\n**Option 2a: API Key via login command**\n\n```\nzilliz login --api-key\n```\n\n**Option 2b: API Key via configure (legacy)**\n\n```\nzilliz configure\n```\n\n- Prompts for an API key (found in Zilliz Cloud console under API Keys)\n- Limitations compared to OAuth login:\n  - Organization switching not available\n  - Available control-plane operations depend on the key's assigned permissions\n\n**Option 3: Environment variable**\n\nUser can add to their shell profile (`.zshrc` / `.bashrc`):\n\n```\nexport ZILLIZ_API_KEY=<your-api-key>\n```\n\nThe 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.\n\nAfter the user completes control-plane authentication, verify it with:\n\n```bash\nzilliz auth status\n```\n\nFor data-plane-only access, verify the endpoint, database, and credential with a non-destructive data command instead of requiring `zilliz auth status` to succeed.\n\n### Configure Subcommands\n\n```bash\nzilliz configure              # Interactive API key setup\nzilliz configure list          # Show all config values\nzilliz configure set <key> <value>  # Set a config value\nzilliz configure get <key>     # Get a config value\nzilliz configure clear         # Clear all credentials\n```\n\n### Switch Organization\n\nThese commands require an interactive terminal. Instruct the user to run in their own terminal:\n\n```\n# Interactive selection\nzilliz auth switch\n\n# Direct switch by org ID\nzilliz auth switch <org-id>\n```\n\n### Logout\n\n```bash\nzilliz logout\n```\n\n### Set Cluster Context\n\nData-plane commands (collection, vector, index, etc.) require an active cluster context.\n\n```bash\n# Set by cluster ID when endpoint discovery is available\nzilliz context set --cluster-id <cluster-id>\n\n# Set an explicit data-plane context when discovery is unavailable\nzilliz context set --cluster-id <cluster-id> --endpoint <url> --database <database-name>\n\n# Change the active database\nzilliz context set --database <db-name>\n```\n\nDo 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.\n\n### View Current Context\n\n```bash\nzilliz context current\n```\n\n## Output Format\n\nAll zilliz-cli commands support `--output json` for structured, machine-readable output. Use this when you need to parse results programmatically:\n\n```bash\nzilliz cluster list --output json\nzilliz collection describe --name <name> --output json\n```\n\nAvailable formats: `json`, `table`, `text`. Default is `text`.\n\n## Capability detection\n\nAvailable 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.\n\n- For control-plane tasks, test the narrowest relevant read command first.\n- For data-plane tasks, confirm the explicit endpoint and database, then test `database list` or `collection list`.\n- If a command is unavailable or denied, report the returned error and continue with independent capabilities when possible.\n- 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.\n\n## Troubleshooting\n\n- **\"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`.\n- **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.\n- **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>`.\n- **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.\n- **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.\n\n## Guidance\n\n- Validate only the capabilities needed for the current task.\n- Treat control-plane discovery and data-plane operations as independent when the available credentials support only one of them.\n- 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.\n- 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.\n- After the user reports setup is complete, verify the narrowest capability needed for the requested task.\n- After setting context, verify with `zilliz context current`.\n- For data-plane commands in other skills, verify that context includes the intended endpoint and database.\n- When a command fails unexpectedly, verify the endpoint, database, credential scope, and current context before drawing conclusions about service support.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}