CLI Guide implemented
This page is for people using the CLI as a real surface, not as a hidden debug tool.
What The CLI Is
The CLI is the contract-first control client for:
- human user and admin workflows;
- operator read and action surfaces;
- scriptable API consumption;
- app and automation integration checks.
It should follow the same public contracts as the web product, not bypass them.
Reading Order
- Authenticate
- Verify active context
- Use project-scoped commands
- Switch to JSON output for scripts
- Use the app/runtime or operator families as needed
Core Model
| Concern | CLI behavior |
|---|---|
| Auth | browser OIDC PKCE is the target human login path; Keycloak password login remains a local/demo stability path |
| Context | project and tenant context are explicit and must be visible |
| Output | human-readable by default, JSON for scripts and automation |
| Contract | commands should match public API and shared-runtime explain/schema surfaces |
Main Command Families
| Family | What it does |
|---|---|
auth | login, identity, context |
projects | list/select project context |
catalog | inspect launchable capacity |
allocations | create/list/release allocations |
nodes | inspect operator-visible node inventory |
billing | read financial posture |
apps | app instance and shared-runtime flows |
schema / explain | machine-readable contract discovery |
Typical Interactive Flow
Local Demo Flow
The stable local flow is:
make build-cli
./dist/gpuaas-cli auth keycloak-login --username dev-user --password dev123 --base-url http://localhost:8081
./dist/gpuaas-cli auth whoami
./dist/gpuaas-cli projects list
./dist/gpuaas-cli catalog list
./dist/gpuaas-cli allocations list
Script / Automation Guidance
- prefer
--output json - assume canonical error envelope
- keep project context explicit
- use service accounts for long-running automation instead of human tokens