Reference

Quick-reference tables for all CLI commands, REST API endpoints, and MCP tools.

---

CLI Commands

Base: cpctl <command>
Auth: cpctl login --token <cp-api-token>

Command	Description
cpctl login	Authenticate with Compute Portal
cpctl logout	Log out and revoke credentials
cpctl whoami	Show current authenticated user
cpctl init	Interactively create cp.json
cpctl link <service>	Link directory to a service
cpctl link <svc-a> <svc-b>	Wire two services together
cpctl unlink	Remove .cp-link
cpctl open [service]	Open service URL in browser
cpctl list	List all services
cpctl deploy	Deploy a service (image, repo, or cp.json)
cpctl redeploy <service>	Re-trigger current deployment
cpctl rollback <service> [id]	Roll back to a previous deployment
cpctl machine list	List services with replica counts
cpctl machine start <name>	Start a service
cpctl machine stop <name>	Stop a service
cpctl machine restart <name>	Restart a service
cpctl machine destroy <name>	Permanently destroy a service
cpctl machine status <name>	Show service health
cpctl logs <name>	Stream service logs
cpctl status [name]	Check platform or service health
cpctl scale <name>	Scale replicas, resources, or HPA
cpctl exec <name> -- <cmd>	Run command inside container
cpctl ssh <name>	Open interactive shell in container
cpctl ps	List running services across all nodes
cpctl env set <service>	Set environment variables
cpctl env list <service>	List environment variables
cpctl env unset <service>	Remove environment variables
cpctl env copy <src> <dst>	Copy env vars between services
cpctl variable	Alias for cpctl env
cpctl environment list	List environments
cpctl environment create	Create an environment
cpctl environment delete	Delete an environment
cpctl environment switch	Switch active environment
cpctl deployment list <service>	List deployment history
cpctl deployment status <service> <id>	Show deployment details
cpctl domain add <service> <domain>	Attach custom domain
cpctl domain list <service>	List domains
cpctl domain status <service> <domain>	Check domain/TLS status
cpctl domain remove <service> <domain>	Remove domain
cpctl volume list [service]	List volumes
cpctl volume add <service> <path>	Attach a volume
cpctl volume delete <service> <name>	Delete a volume
cpctl volume browse <service>	Open shell to browse volumes
cpctl volume download <service> <remote> [local]	Download file from container
cpctl volume upload <service> <local> <remote>	Upload file to container
cpctl db create <type>	Create a managed database
cpctl db list	List databases
cpctl db url <name>	Print connection URL
cpctl db attach <database> <service>	Inject DATABASE_URL into a service
cpctl db destroy <name>	Destroy a database
cpctl connect <name>	Open interactive database shell
cpctl bucket create <name>	Create an S3 bucket
cpctl bucket list	List S3 buckets
cpctl bucket credentials <name>	Show bucket credentials
cpctl bucket delete <name>	Delete an S3 bucket
cpctl service clone <src> <dst>	Clone a service
cpctl preview enable <service>	Enable PR preview environments
cpctl preview disable <service>	Disable PR previews
cpctl preview list <service>	List active preview deployments
cpctl iac init	Generate cp.yaml from live services
cpctl iac up [--dry-run] [--yes] [-f file]	Apply cp.yaml
cpctl iac down	Destroy resources in cp.yaml
cpctl deploy-hook create <service>	Create an inbound deploy hook
cpctl deploy-hook list <service>	List deploy hooks
cpctl deploy-hook delete <service> <id>	Delete a deploy hook
cpctl webhook create <url>	Register an outbound webhook
cpctl webhook list	List outbound webhooks
cpctl webhook delete <id>	Delete an outbound webhook
cpctl firewall add <service>	Add firewall rule
cpctl firewall list <service>	List firewall rules
cpctl firewall remove <service> <id>	Remove a firewall rule
cpctl firewall off <service>	Remove all firewall rules
cpctl configmap create <name>	Create a config map from file(s)
cpctl configmap list	List config maps
cpctl configmap delete <name>	Delete a config map
cpctl expose <service> --port <n>	Expose a service port over raw TCP
cpctl expose list <service>	List exposed TCP ports
cpctl expose delete <service> <port>	Remove a TCP expose
cpctl tcp-proxy create <service>	Create a TCP proxy
cpctl tcp-proxy list <service>	List TCP proxies
cpctl tcp-proxy delete <service> <port>	Delete a TCP proxy
cpctl static-ip enable <service>	Enable static outbound IP
cpctl static-ip show <service>	Show static IP
cpctl static-ip disable <service>	Release static IP
cpctl invite create	Issue single-use invitation token
cpctl invite list	List active invitation tokens
cpctl invite revoke <id>	Revoke a pending invitation
cpctl quota	Show compute quota usage
cpctl metrics <service>	View service metrics
cpctl gpu list	List GPU inventory
cpctl gpu status <service>	Show GPU utilization
cpctl gpu reserve	Reserve GPU capacity
cpctl gpu run	Run a one-shot GPU job
cpctl node list	List bare-metal nodes
cpctl node inspect <id>	Show node hardware specs
cpctl node reserve <id>	Reserve a node for dedicated use
cpctl node release <id>	Release a reserved node
cpctl region list	List regions
cpctl region verify <service>	Confirm data residency
cpctl policy set	Set org-wide data residency policy
cpctl github pat <token>	Store GitHub PAT for private images
cpctl billing balance	Show current balance and burn rate
cpctl billing topup init	Get a deposit address for crypto top-up
cpctl billing topup verify	Submit transaction ID to confirm top-up
cpctl billing usage	Show itemized spend
cpctl billing alert	Set a low-balance alert threshold
cpctl billing history	Show invoice history
cpctl pay setup	Link a card for per-call machine payments
cpctl pay status	Show linked payment method
cpctl pay authorize <service> <amount>	Pre-authorize a per-call charge
cpctl pay history	List per-call payment charges
cpctl sandbox create	Create an ephemeral GPU sandbox
cpctl sandbox list	List sandboxes
cpctl sandbox exec <id> -- <cmd>	Run command inside a sandbox
cpctl sandbox status <id>	Show sandbox health
cpctl sandbox destroy <id>	Destroy a sandbox
cpctl docs	Open documentation in browser
cpctl upgrade	Upgrade the CLI
cpctl uninstall	Remove cpctl binary (--purge to also remove ~/.cp)
cpctl version	Print CLI version

---

REST API Endpoints

Base URL: https://api.computeportal.io
Auth: Authorization: Bearer cp_live_<hex>

Services

Method	Path	Description
GET	/v1/services	List all services
POST	/v1/services	Deploy a new service
GET	/v1/services/:name	Get service details
PATCH	/v1/services/:name	Update service (image, env vars, replicas)
DELETE	/v1/services/:name	Delete a service
POST	/v1/services/:name/start	Start a stopped service
POST	/v1/services/:name/stop	Stop a running service
POST	/v1/services/:name/restart	Restart a service
POST	/v1/services/:name/redeploy	Re-trigger deployment
POST	/v1/services/:name/scale	Scale replicas or resources
POST	/v1/services/:name/autoscale	Configure or disable HPA
GET	/v1/services/:name/autoscale	Get current HPA config
POST	/v1/services/:name/rollback	Roll back to previous deployment
GET	/v1/services/:name/logs	Fetch recent log output
GET	/v1/services/:name/build-logs	Stream build logs (SSE)
GET	/v1/services/:name/metrics	Get CPU/memory/network metrics
GET	/v1/services/:name/gpu	Get GPU utilization
GET	/v1/services/:name/deployments	List deployment history
GET	/v1/services/:name/deployments/:id	Get a specific deployment
GET	/v1/services/:name/env	List environment variables
POST	/v1/services/:name/env	Set environment variables
POST	/v1/services/:name/env/unset	Remove environment variables
GET	/v1/services/:name/volumes	List attached volumes
POST	/v1/services/:name/volumes	Attach a volume
DELETE	/v1/services/:name/volumes/:id	Delete a volume
GET	/v1/status	Platform health check

Domains

Method	Path	Description
POST	/v1/services/:name/domains	Attach a custom hostname
GET	/v1/services/:name/domains	List all hostnames
GET	/v1/services/:name/domains/:hostname	Get domain/TLS status
DELETE	/v1/services/:name/domains/:hostname	Remove a custom hostname

Deploy Hooks & Webhooks

Method	Path	Description
POST	/v1/services/:name/hooks	Create a deploy hook
GET	/v1/services/:name/hooks	List deploy hooks
DELETE	/v1/services/:name/hooks/:id	Delete a deploy hook
POST	/v1/services/:name/hooks/:id/trigger	Trigger a deploy (inbound hook endpoint)
POST	/v1/webhooks	Register an outbound webhook
GET	/v1/webhooks	List outbound webhooks
DELETE	/v1/webhooks/:id	Delete an outbound webhook

Config Maps

Method	Path	Description
POST	/v1/configmaps/upload-token	Get presigned S3 upload URLs for files
POST	/v1/configmaps	Commit uploaded files as a config map
GET	/v1/configmaps	List all config maps
DELETE	/v1/configmaps/:name	Delete a config map

TCP Expose

Method	Path	Description
POST	/v1/services/:name/expose	Expose a port over raw TCP
GET	/v1/services/:name/expose	List exposed TCP ports
DELETE	/v1/services/:name/expose/:port	Remove a TCP expose

Firewall, TCP Proxy & Static IP

Method	Path	Description
POST	/v1/services/:name/firewall	Add a firewall rule
GET	/v1/services/:name/firewall	List firewall rules
DELETE	/v1/services/:name/firewall/:id	Remove a firewall rule
DELETE	/v1/services/:name/firewall	Remove all firewall rules
POST	/v1/services/:name/tcp-proxy	Create a TCP proxy
GET	/v1/services/:name/tcp-proxy	List TCP proxies
DELETE	/v1/services/:name/tcp-proxy/:port	Delete a TCP proxy
POST	/v1/services/:name/static-ip	Enable static outbound IP
GET	/v1/services/:name/static-ip	Get static IP
DELETE	/v1/services/:name/static-ip	Disable static IP

Preview Environments

Method	Path	Description
POST	/v1/services/:name/previews/enable	Enable PR preview environments
POST	/v1/services/:name/previews/disable	Disable PR previews
GET	/v1/services/:name/previews	List active previews

GPU & Nodes

Method	Path	Description
GET	/v1/gpu/nodes	List GPU nodes and availability
POST	/v1/gpu/reserve	Reserve GPU capacity
POST	/v1/gpu/jobs	Run a one-shot GPU job
GET	/v1/gpu/jobs/:id/logs	Get GPU job logs
GET	/v1/nodes	List compute nodes
GET	/v1/nodes/:id	Get node details
POST	/v1/nodes/:id/reserve	Reserve a node
POST	/v1/nodes/:id/release	Release a reserved node
GET	/v1/regions	List available regions

Databases

Method	Path	Description
GET	/v1/databases	List databases
POST	/v1/databases	Create a database
GET	/v1/databases/:name	Get database details
DELETE	/v1/databases/:name	Destroy a database

Object Storage

Method	Path	Description
POST	/v1/storage/buckets	Create a bucket
GET	/v1/storage/buckets	List buckets
GET	/v1/storage/buckets/:name/credentials	Get bucket credentials
DELETE	/v1/storage/buckets/:name	Delete a bucket

Environments

Method	Path	Description
GET	/v1/environments	List environments
POST	/v1/environments	Create an environment
DELETE	/v1/environments/:name	Delete an environment

Sandboxes

Method	Path	Description
GET	/v1/sandboxes	List sandboxes
POST	/v1/sandboxes	Create a sandbox
GET	/v1/sandboxes/:id	Get sandbox details
DELETE	/v1/sandboxes/:id	Destroy a sandbox

Agent Account Invitations

Method	Path	Description
POST	/v1/users/invitations	Issue an invitation token
GET	/v1/users/invitations	List active invitation tokens
DELETE	/v1/users/invitations/:id	Revoke an invitation
POST	/v1/users/redeem	Redeem invitation token → creates new account (public, rate-limited)

Machine Payments

Method	Path	Description
GET	/v1/pay/status	Get linked payment method
POST	/v1/pay/setup	Start card setup
GET	/v1/pay/setup/poll	Poll for setup completion
POST	/v1/pay/authorize	Pre-authorize a per-call charge
GET	/v1/pay/history	List charge history

Billing

Method	Path	Description
GET	/v1/billing/balance	Current balance and burn rate
GET	/v1/billing/usage	Current billing cycle usage
GET	/v1/billing/history	Past invoices
POST	/v1/billing/topup/init	Get deposit address for crypto top-up
POST	/v1/billing/topup/verify	Submit transaction ID to confirm

GitHub Integration

Method	Path	Description
GET	/v1/github/token	Fetch short-lived GitHub installation token for private repo access

---

MCP Tools

Endpoint: https://mcp.computeportal.io/mcp (Streamable HTTP) — or local stdio via cpctl mcp serve.
Auth: Authorization: Bearer cp_live_<hex> per request (same token cpctl login stores). The server carries no credential of its own.

Safety rails: mutating tools accept dry_run: true to return a Plan with a single-use confirm_token (2-minute TTL, bound to tool+args). The three destructive tools (cp_destroy, cp_sandbox_destroy, cp_domain_remove) require that flow — all other mutations accept dry_run as an opt-in.

Total tools: 23.

Service & Deploy

Tool	Kind	Description
cp_deploy	mutating	Deploy a container image as a new or updated service
cp_service_list	read	List all deployed services
cp_service_status	read	Status, replicas, and health for a service
cp_service_logs	read	Fetch recent log lines
cp_scale	mutating	Scale a service to N replicas
cp_destroy	destructive	Delete a service — requires dry_run + confirm_token
cp_env_set	mutating	Set environment variables on a service

GPU & Nodes

Tool	Kind	Description
cp_gpu_list	read	List available GPU resources by region
cp_gpu_reserve	mutating	Reserve a GPU slot for a service
cp_gpu_run	mutating	Launch a one-shot GPU job
cp_node_list	read	List compute nodes
cp_region_list	read	List available regions

Domains

Tool	Kind	Description
cp_domain_add	mutating	Attach a custom hostname to a service
cp_domain_list	read	List hostnames on a service
cp_domain_remove	destructive	Remove a hostname — requires dry_run + confirm_token

Databases & Sandboxes

Tool	Kind	Description
cp_db_create	mutating	Provision a managed database
cp_sandbox_create	mutating	Launch a transient sandbox environment
cp_sandbox_exec	mutating	Run a command inside a sandbox
cp_sandbox_destroy	destructive	Delete a sandbox — requires dry_run + confirm_token

Billing & Catalog

Tool	Kind	Description
cp_billing_balance	read	Current balance and burn rate
cp_billing_usage	read	Current cycle usage
cp_billing_resync	mutating	Force a billing reconciliation
cp_catalog_list	read	Enumerate catalog items (regions, GPU SKUs, DB engines)

---

CLI ↔ Platform compatibility

The cpctl CLI and the Compute Portal platform API version independently. Any CLI in the matrix below works against any platform version in the same row.

CLI (cpctl)	Platform API	Notes
0.3.26+	0.1.1+	cpctl deploy --dry-run now calls /v1/services/precheck for plan coverage + estimated monthly cost (exits 4 when rejected). CLI-local errors (unknown subcommand → exit 127, unknown flag → exit 2) emit a JSON envelope under --json. billing resync backfills invoices and prints a cpctl billing history hint.
0.3.22–0.3.25	0.1.0+	Read-only (--read-only) and uncapped (--unlimited) scoped API keys; --limit 0 is now rejected. pay status emits structured JSON. Token-expiry label clarified.
0.3.21	0.1.0+	OS keychain token storage (macOS Keychain / Secret Service / Credential Manager) with 0600 file fallback. Examples: block on every top-level command.
0.3.17–0.3.20	0.1.0+	--json envelope + --dry-run / --yes on every write command (0.3.19+). AUTH_REQUIRED / NOT_FOUND exit codes correct from 0.3.20.
0.3.0–0.3.16	0.1.0+	Core deploy / scale / env / domain / GPU / billing. No machine-readable error envelope.
older 0.2.x	0.1.0+	Deprecated; please upgrade. Missing invite-token flow and Retry-After header handling.

How to check: cpctl version prints the CLI build. The platform version is printed as part of cpctl status under the platform key.

Upgrade path: cpctl upgrade always moves to the latest published release at install.computeportal.io. Pin a specific version with CP_VERSION=v0.3.21 curl -fsSL https://install.computeportal.io | sh.