WAYSCloud CLI

The official command-line tool for managing WAYSCloud resources. Manage servers, DNS, storage, and access the interactive CloudShell — all from your terminal.

Install

pip install wayscloud-cli

Requires Python 3.9+. Installs the cloud binary.

Authenticate

The CLI uses Personal Access Tokens (PAT) for authentication. Create a token in the dashboard under Account → API Keys.

cloud login --token wayscloud_pat_abc1234567_yourSecretTokenHere

The token is validated against the API before being saved. Credentials are stored in ~/.wayscloud/credentials with chmod 600.

Token resolution priority:

1. --token flag (any command)
2. WAYSCLOUD_TOKEN environment variable
3. ~/.wayscloud/credentials file

Token scopes

Tokens have granular scopes that control what the CLI can do:

Scope	Access
vps:read	List and view servers
vps:write	Create, start, stop, delete servers
dns:read	List zones and records
dns:write	Create and modify DNS
storage:read	List buckets
storage:write	Create buckets and keys
database:read	List databases
database:write	Create and delete databases
shell:connect	Connect to CloudShell

By default, new tokens have read-only access. Enable write scopes explicitly when creating the token.

---

Commands

Account

# Check your identity
cloud whoami

# Log out (removes saved token)
cloud logout

VPS

# List all servers
cloud vps list

# Filter by status or region
cloud vps list --status running
cloud vps list --region NO

# Server details
cloud vps info vps-abc123

# Real-time status (power state, CPU, memory, uptime)
cloud vps status vps-abc123

# Power management
cloud vps start vps-abc123
cloud vps stop vps-abc123

# Delete (requires explicit confirmation)
cloud vps delete vps-abc123 --confirm

# Browse plans, regions, and OS templates
cloud vps plans
cloud vps plans --region SE
cloud vps regions
cloud vps os-templates

Interactive Shell

Connect to the browser-based CloudShell directly from your terminal:

cloud shell connect

This opens a WebSocket connection to CloudShell, giving you access to all cloud commands interactively — including services not yet available as standalone CLI commands (DNS, databases, storage, IoT, LLM, SMS, and more).

The shell connection requires the shell:connect scope on your token.

---

Output formats

Default: Human-readable tables with colors (Rich library).

cloud vps list
┌─────────────┬──────────────────┬───────────────┬─────────┐
│ ID          │ Name             │ IP            │ Status  │
├─────────────┼──────────────────┼───────────────┼─────────┤
│ vps-abc123  │ Web Server       │ 203.0.113.42  │ running │
└─────────────┴──────────────────┴───────────────┴─────────┘

JSON: Machine-readable output for scripting.

cloud vps list --json

[
  {
    "id": "vps-abc123",
    "display_name": "Web Server",
    "ipv4_address": "203.0.113.42",
    "status": "running"
  }
]

JSON contract:

• List commands return arrays
• Info commands return objects
• Errors return {"error": "code", "code": 2, "message": "..."}

Disable colors with --no-color or set NO_COLOR=1.

---

Exit codes

Code	Meaning
0	Success
1	Usage error (missing arguments, invalid flags)
2	Authentication or permission error (401, 403)
3	Network or server error

---

Scripting examples

List running servers as JSON and filter with jq:

cloud vps list --json | jq '.[] | select(.status == "running") | .ipv4_address'

Stop all servers in a region:

cloud vps list --json --region NO | jq -r '.[].id' | xargs -I{} cloud vps stop {}

Use in CI/CD with environment variable:

export WAYSCLOUD_TOKEN="wayscloud_pat_abc123_secret"
cloud vps status vps-abc123 --json

---

Security

• Bearer-only authentication — Tokens are sent as Authorization: Bearer headers only, never in query strings or other formats
• Error sanitization — Server responses never include internal IPs, hostnames, or stack traces
• Credential protection — ~/.wayscloud/credentials is created with chmod 600
• Scope enforcement — Every API call validates scopes. A read-only token cannot perform write operations.
• Audit logging — All CLI actions are logged with token ID, customer ID, and IP address

---

CLI vs CloudShell vs API

	CLI	CloudShell	REST API
Where	Your terminal	Browser (console)	Any HTTP client
Auth	PAT token	Dashboard session	API key or PAT
Services	VPS + shell connect	All services	All services
Output	Tables or JSON	Interactive terminal	JSON
Scripting	Yes (--json + jq)	No	Yes
Best for	Automation, CI/CD	Quick management	Application integration

The CLI connects to the same API endpoints as the dashboard. For services not yet available as standalone CLI commands, use cloud shell connect to access the full CloudShell command set.

---

Troubleshooting

"Invalid token" on login: Your PAT may be expired or revoked. Create a new token in the dashboard.

"Scope denied" errors: Your token does not have the required scope. Create a new token with the needed permissions.

"Connection refused" on shell connect: Check your network connection. The shell connects to wss://shell.wayscloud.services/ws.

Rate limiting: The CLI is limited to 300 requests per minute. If you hit this limit, space out your requests.

---

Next steps

• CloudShell — full CloudShell documentation
• Authentication — PAT and API key details
• Python Integration — use the API from Python
• Terraform Provider — infrastructure as code