Weaviate Cloud CLI (wcloud)
wcloud is a command-line interface for Weaviate Cloud (WCD). You can use it from a terminal, and AI coding agents can use it too.
wcloud creates clusters, lists them, and shows their details. It also lists regions. It does not touch the data in a cluster. For that, use a client library. It cannot delete a cluster, change a plan, or manage billing, users, or organizations. Use the Weaviate Cloud console for those.
AI coding agents use the same wcloud you do. An agent learns it by running wcloud guide or wcloud skill install.
Install the wcloud CLI
- Homebrew (recommended)
- npm
- Go
brew install weaviate/tap/weaviate-cloud
Homebrew is recommended on macOS and Linux. You do not need Go installed.
npm install -g weaviate-cloud
npm installs the same program. Use it on Windows (x64).
go install github.com/weaviate/weaviate-cloud/cmd/wcloud@latest
This builds the program from source. For the minimum Go version, see the wcloud README.
Check the installation:
wcloud version
For the details of each install method, see the README's Install section.
Sign in
wcloud auth login
wcloud auth whoami
wcloud auth logout
You can only sign in through a browser, so wcloud cannot sign in on a machine without a browser. The browser must run on the same machine as wcloud.
Once you are signed in, wcloud renews your sign-in on its own. For the sign-in timeout, the local ports it uses, and where it saves your sign-in details, see the README's Authentication section.
Create a free cluster
wcloud cluster create --name my-cluster --wait
--name is optional. --wait keeps the command running until the cluster is READY. Without it, run wcloud cluster status until it reports READY.
The result includes the cluster's REST and gRPC endpoints and a one-time API key. The key is shown once, either by wcloud cluster create --wait when the cluster becomes READY, or by the first wcloud cluster get after it is ready. wcloud never stores it, and every later call shows the key field empty, so save it when you see it. To add, rotate, or delete cluster API keys afterwards, see Authentication.
By default, wcloud creates a free cluster in eu-central-1, currently the only region. --tier accepts only free. For a paid Shared Cloud cluster or advanced settings, use the console as in Create a cluster. For every flag, see the README's Commands section.
View clusters and regions:
wcloud cluster list
wcloud cluster get <cluster-id>
wcloud cluster status <cluster-id>
wcloud region list
Once a cluster is READY, connect a client library to it.
Limits and boundaries
There is no delete command
Delete a cluster in the Weaviate Cloud console. Pick it with the CLUSTER selector in the left sidebar, then delete it from its Dashboard.
One free cluster per account
Each account gets one free cluster at a time, across every organization. A suspended cluster still uses the slot. wcloud cluster list shows only the current organization, so it may not show the cluster that uses your slot. The console shows all organizations. To free the slot, delete the cluster there or upgrade to a paid plan. Free clusters explains when a free cluster is suspended or deleted. For current limits, see Free tier allowance.
When the slot is taken, wcloud cluster create fails with the error code quota_exceeded. Retrying does not help. For every error code and exit code, see the README's Exit codes section.
Use wcloud from an AI coding agent
wcloud guide
wcloud guide prints a Markdown guide written for AI coding agents. It always matches the installed version of wcloud. It ignores --output.
Once the cluster is ready, the guide tells the agent what to offer next. First comes weaviate/agent-skills, which works in the same session. Next is the cluster's MCP server, which most coding agents only pick up after a restart. The client libraries are the last option.
wcloud skill install --all
This writes the guide as a SKILL.md file in the place where each supported coding agent looks for it. --harness picks which coding agents to install it for. --project writes it to the current project instead of your user directory. For the supported coding agents and the install options, see the README's coding agent section.
Cluster creation requests include an X-Provisioned-By header whose value is one word, cli or agent, and it is sent only to the Weaviate Cloud API.
JSON output
Commands that return a result print a JSON object with data or error, plus metadata. -o json always prints JSON. The default, auto, picks JSON when the output is not going to a terminal, for example when it goes to a file or another command. It also picks JSON when the CI environment variable is set. Scripts can rely on the exit codes staying the same. For the JSON format, the auto rules, and the full list of exit codes, see the README's Status, Commands, and Exit codes sections.
Further resources
Support
If you use Weaviate Cloud (Database cluster(s) or Weaviate product in the cloud) or have a self-hosted support package, open a ticket in the Support Portal or email Weaviate support directly. To add a support plan, contact Weaviate sales.
Use the Support Portal for direct help from the Weaviate team: open and track tickets, and we'll respond in line with your support plan. The Community Forum is open to everyone, and a great place to ask questions, get help with your cluster, and connect with other developers. For all the ways to get help, see the Support overview.
