# 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
```bash
make build-cli
```

Binary output:
- `dist/gpuaas-cli`

## Demo flow (copy/paste)
```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.