Skip to content

Local CLI Demo Runbook

Purpose: - Run a stable CLI demo on local stack without changing UI flows.

Scope for this demo

  • CLI binary build
  • Auth via local Keycloak (auth keycloak-login)
  • Project context verification
  • Catalog, node, billing, allocation list calls
  • App-platform introspection (schema, explain)
  • Tenant-shared runtime read flows

Note: - gpuaas auth login is now the browser OIDC PKCE path. It is the target user flow for brokered identities. - For demo stability, use auth keycloak-login below.

Prerequisites

  • Local stack is running:
  • make dev-up
  • API reachable:
  • curl -fsS http://localhost:8081/api/v1/healthz | jq .
  • Keycloak reachable:
  • curl -fsS http://localhost:8080/realms/gpuaas/.well-known/openid-configuration | jq .issuer

Build CLI

make build-cli

Binary output: - dist/gpuaas-cli

Demo flow (copy/paste)

# 1) Login with seeded dev user via Keycloak
./dist/gpuaas-cli auth keycloak-login \
  --username dev-user \
  --password dev123 \
  --base-url http://localhost:8081

# 2) Show resolved identity + tenant/project context
./dist/gpuaas-cli auth whoami

# 3) Show projects and active project marker (*)
./dist/gpuaas-cli projects list

# 4) Show available GPU catalog
./dist/gpuaas-cli catalog list

# 5) Show node inventory (status + occupancy)
./dist/gpuaas-cli nodes list

# 6) Show current balance
./dist/gpuaas-cli billing balance

# 7) Show allocation history/list in active project context
./dist/gpuaas-cli allocations list

# 8) Show shared runtime schema for agent/debug use
./dist/gpuaas-cli --output json schema shared-runtime

# 9) Explain a tenant-shared runtime command in machine-readable form
./dist/gpuaas-cli --output json explain apps shared-runtimes get

Platform-control demo flow

Use this for the public platform-control demo environment. The HOME=$(mktemp -d) pattern keeps the demo session isolated from any existing operator CLI config.

# 1) Build the CLI from the current checkout
make build-cli

# 2) Create an isolated CLI config directory for the demo terminal
export GPUAAS_CLI_HOME="$(mktemp -d)"
export HOME="$GPUAAS_CLI_HOME"

# 3) Login through the platform-control Keycloak issuer
./dist/gpuaas-cli auth keycloak-login \
  --username dev-admin \
  --password admin123 \
  --base-url https://gpuaas-dev-app.tailfe39f5.ts.net/backend \
  --kc-url https://gpuaas-dev-auth.tailfe39f5.ts.net \
  --realm gpuaas \
  --client-id gpuaas-api \
  --client-secret dev-client-secret

# 4) Show identity and active project context
./dist/gpuaas-cli auth whoami
./dist/gpuaas-cli context show
./dist/gpuaas-cli projects list

# 5) Show demo-safe platform state
./dist/gpuaas-cli catalog list
./dist/gpuaas-cli billing balance
./dist/gpuaas-cli allocations list
./dist/gpuaas-cli apps instances list
./dist/gpuaas-cli nodes list

# 6) Optional JSON output for scripts or terminal zoom-ins
./dist/gpuaas-cli --output json auth whoami
./dist/gpuaas-cli --output json apps instances list

# 7) Cleanup isolated CLI config after the demo
rm -rf "$GPUAAS_CLI_HOME"
unset GPUAAS_CLI_HOME

Validated on platform-control on 2026-04-22: - API base: https://gpuaas-dev-app.tailfe39f5.ts.net/backend - Auth base: https://gpuaas-dev-auth.tailfe39f5.ts.net - Login, context, projects, catalog, billing, allocations, app instances, and nodes list all returned successfully.

Optional tenant-shared runtime demo

Use this only if you already have a valid org id and seeded shared runtime data in your environment.

# List tenant-shared runtimes
./dist/gpuaas-cli apps shared-runtimes list --org-id <org_id>

# Get one tenant-shared runtime
./dist/gpuaas-cli apps shared-runtimes get --org-id <org_id> --id <shared_runtime_id>

# List attached projects
./dist/gpuaas-cli apps shared-runtimes attachments list \
  --org-id <org_id> \
  --runtime-id <shared_runtime_id>

Optional create/release demo

Use this only if you already have a known valid node id for provisioning mode in your environment.

# Create allocation (optionally pin node)
./dist/gpuaas-cli allocations create \
  --scheduler-type bare_metal \
  --node-id <node_uuid>

# Watch list again
./dist/gpuaas-cli allocations list

# Release allocation
./dist/gpuaas-cli allocations release --id <allocation_uuid>

Quick troubleshooting

  • token_invalid after login:
  • re-run auth keycloak-login
  • verify Keycloak realm/client settings in local compose
  • project context required:
  • run ./dist/gpuaas-cli projects list
  • set explicitly with ./dist/gpuaas-cli projects use --id <project_id>
  • API errors:
  • CLI prints canonical error envelope values (code, message, correlation_id) for log/trace lookup.