API, CLI & AI assistants

What you can read

One read-only surface, three ways in: the cw command line, AI assistants over MCP, and the HTTP API behind both. All three answer the same questions:

Create an API token

Name the token, choose the namespaces it may read and what it may read there (apps, servers, backups, runs, logs, attention…), and how long it lives: one week, 30 to 365 days, or a number of days you pick. A token never reaches more than your own access, and if your access changes, the token follows at once.

The token is shown once. It starts with cwk_; keep it like a password. You can rename it, change its namespaces or what it may read later, and revoke it at any time — anything using it stops working immediately.

A token reads only what it was given when it was made: to let an older token read something added since — projects, restore points, URLs — edit it and tick it.

Install the CLI

macOS and Linux:

curl -fsSL https://www.cloudwady.com/install.sh | sh

The script downloads the build for your machine, checks it against the release checksums and installs cw into /usr/local/bin or ~/.local/bin — never with sudo. With Homebrew on macOS:

brew install kingswady/tap/cw

Windows, in PowerShell:

irm https://www.cloudwady.com/install.ps1 | iex

It checks the download the same way, installs cw.exe into your own AppData\Local\Programs\cw and adds that folder to your PATH — no administrator needed; open a new terminal afterwards. To do it by hand instead, download cw_windows_amd64.zip from the latest release, unzip it, and put cw.exe in a folder on your PATH.

Everywhere, cw update keeps it current (brew upgrade cw if Homebrew installed it). From cw 0.9.0 on, cw offers to update itself when a newer release is out, and checks each release's signature before installing it.

CW_DOWNLOAD_BASE=https://github.com/kingswady/cwcli/releases cw update

cw login        # paste the token; it is kept in your system keychain
cw whoami       # who the token acts as, its namespaces, and when it expires
cw use          # switch between platforms you logged in to
cw namespaces   # the namespaces the token reads, and your level in each

Tab completion: cw completion zsh (or bash, fish) prints the script for your shell; the README says where to put it.

Commands

Every read command takes --json (the API's own answer, for jq), --namespace acme, --limit, --offset and --color auto|always|never. Exit codes: 0 success, 1 the platform refused or failed, 2 a mistake on the command line, 3 cw attention found something.

Connect an AI assistant (MCP)

MCP lets an assistant such as Claude, Cursor or Codex call CloudWady's read functions itself. cw mcp connects it with the token you logged in with:

claude mcp add -s user cloudwady -- cw mcp

Claude Desktop, Cursor and most other assistants take the same server in their configuration:

{ "mcpServers": { "cloudwady": { "command": "cw", "args": ["mcp"] } } }

An assistant that connects over HTTP can use https://www.cloudwady.com/mcp with the header Authorization: Bearer cwk_…. Then ask in plain words — "What needs attention on CloudWady?", "Why did the last deploy of shop fail?" — or start from the prompts it offers: triage, why_failed and app_health.

In scripts and CI

CW_TOKEN takes the place of the saved token and CW_URL of the saved platform:

export CW_TOKEN=cwk_…      # from your CI secret store
cw runs --app shop --state error --json
cw attention --json > attention.json || ./notify-team.sh attention.json

The HTTP API

Everything above is GET https://www.cloudwady.com/api/v1/… with Authorization: Bearer cwk_…. An answer is {"data": …}; a refusal is {"error": {"code": …, "message": …}} with a matching HTTP status. The full reference is the OpenAPI document at /api/v1/openapi.json.

curl -H "Authorization: Bearer $CW_TOKEN" https://www.cloudwady.com/api/v1/attention

Every answer carries X-Token-Expires-At, so a script can warn before its token stops working.

Limits & security

• Read-only. No token can change anything.
• Your access, no more. A token reads only the namespaces you gave it and sees what the dashboard shows your role there; a revoked role or namespace takes effect on the next request.
• Secrets stay out. Passwords, keys and credentials are never part of an answer, and log lines are masked.
• Rate limit. 120 requests a minute per token and 300 per user. Past it the answer is 429 with Retry-After; cw logs --follow waits and carries on.
• Tokens. Stored hashed, shown once, expiring on the date you chose. If one may have leaked, revoke it in My Settings.