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.

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. On Windows, 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.

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

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, within your own role; 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.