CLI And SDK Guide

The CLI and SDK automate AI Cloud workflows without browser interaction. The current CLI command name is gpuaas; public product naming is AI Cloud while the CLI package is being renamed.

Configure The CLI

Your environment owner should provide the API base URL and, when terminal access is enabled, the terminal gateway URL.

gpuaas --base-url https://api.<your-ai-cloud-domain> auth login

gpuaas auth whoami
gpuaas context show

Normal user login uses browser OIDC with PKCE. The CLI opens the browser, waits for the local callback, saves the returned session context, and prints the config path it updated.

The CLI stores local config under ~/.gpuaas-cli/config.json. Set GPUAAS_CLI_HOME=<isolated-config-dir> to isolate credentials for a test, CI smoke, or multi-environment walkthrough. The directory is created with user-only permissions and the config file is written with user-only read/write permissions.

CLI Authentication Flow

gpuaas auth login signs in through the environment identity provider. Use --no-browser when the terminal cannot open a browser; copy the printed URL into a browser that can reach the environment.

gpuaas --base-url https://api.<your-ai-cloud-domain> auth login

# Headless or remote shell
gpuaas --base-url https://api.<your-ai-cloud-domain> auth login --no-browser

gpuaas auth whoami
gpuaas context show --output json

gpuaas auth whoami verifies the saved token, prints the current user, role, tenant, and project context, and refreshes the active project in the local config when the API returns one.

Development and local bootstrap environments may expose password-based test login. Do not use this for normal user onboarding.

gpuaas --base-url https://api.<dev-ai-cloud-domain> auth dev-login \
  --username <dev-user> \
  --password '<temporary development password>'

Where CLI Credentials Are Stored

Item	Location or behavior
Config file	~/.gpuaas-cli/config.json
Directory mode	user-only directory permissions
File mode	user-only read/write permissions
Access token	stored locally for API calls
Refresh token	stored locally when returned by the environment
Project context	stored as project_id and sent as X-Project-ID
Tenant context	stored as org_id when returned by the environment
Terminal gateway	stored when configured for terminal workflows

gpuaas context show reports whether access and refresh tokens are present without printing token values:

{
  "base_url": "https://api.<your-ai-cloud-domain>",
  "project_id": "<project-id>",
  "org_id": "<tenant-id>",
  "username": "<username>",
  "identity_type": "user",
  "config_path": "~/.gpuaas-cli/config.json",
  "session_present": true,
  "refresh_session_present": true
}

Example shape with private values redacted:

{
  "api_base_url": "https://api.<your-ai-cloud-domain>",
  "sessionValue": "redacted",
  "refreshSessionValue": "redacted",
  "project_id": "<project-id>",
  "org_id": "<tenant-id>",
  "username": "<username>",
  "terminal_gateway_url": "wss://terminal.<your-ai-cloud-domain>"
}

Do not commit, paste, or attach this file to support tickets. If it is exposed, log out, rotate the affected credentials, and ask the tenant admin or operator to invalidate the session if needed.

Logout And Token Hygiene

Use logout when a workstation is shared, when a token may have been exposed, or when switching between environments.

gpuaas auth logout

Logout calls the environment logout endpoint when possible, then removes the saved access token, refresh token, tenant, project, and username from the local config.

For CI or automation, prefer a service-account credential model when your tenant enables it. Store automation secrets in the CI secret store, not in a checked-in config file.

Service Account Automation

Service accounts are project-scoped automation identities. Use them for CI, scheduled jobs, artifact publishing, smoke tests, or controller processes that should not run as a human user.

Create the identity from a human admin session:

gpuaas service-accounts create \
  --project-id <project_id> \
  --name "CI deployer" \
  --slug ci-deployer

The create command prints a key ID and a client secret. The secret is shown once. Store it in the CI secret store or deployment secret manager.

Mint a short-lived service-account token for automation:

export GPUAAS_CLI_HOME=/secure/ci/gpuaas-cli

gpuaas --base-url https://api.<your-ai-cloud-domain> auth service-account-token \
  --service-account-id <service_account_id> \
  --key-id <key_id> \
  --client-secret "$AI_CLOUD_SERVICE_ACCOUNT_SECRET"

gpuaas context set project-id <project_id>
gpuaas context show

Then run project-scoped commands normally:

gpuaas apps artifacts publish-intent --project-id <project_id> --output json
gpuaas apps instances list --project-id <project_id> --output table
gpuaas billing usage --project-id <project_id> --limit 20 --output json

Rotate or disable credentials from an admin session:

gpuaas service-accounts rotate-key --project-id <project_id> --id <service_account_id>
gpuaas service-accounts disable --project-id <project_id> --id <service_account_id>

Use a separate GPUAAS_CLI_HOME for automation so service-account tokens do not overwrite a developer's interactive login.

Project Context

The CLI sends the saved project as X-Project-ID for project-scoped commands. Some commands also accept a project override.

gpuaas allocations list --project-id <project_id> --output json

If a command returns an ownership or permission error, run gpuaas auth whoami and confirm the tenant and project before retrying.

Common CLI Commands

# Catalog and account state
gpuaas catalog list --output table
gpuaas billing balance
gpuaas billing usage --limit 20 --json

# Runtime state
gpuaas allocations list --status active --output table
gpuaas allocations list --project-id <project_id> --output json

# Cleanup
gpuaas allocations release --id <allocation_id> --project-id <project_id>

# Terminal where supported
gpuaas terminal connect --allocation-id <allocation_id> \
  --gateway-url wss://terminal.<your-ai-cloud-domain>

Use CLI output as support evidence only after removing private tokens or secrets.

REST Basics

Use bearer authentication and project context where the endpoint requires it. The examples below assume AI_CLOUD_SESSION contains a valid short-lived session value from the login or service-account flow.

export AI_CLOUD_API="https://api.<your-ai-cloud-domain>"
export AI_CLOUD_SESSION="<short-lived-session-value>"
export AI_CLOUD_AUTH_HEADER="Authorization: <bearer auth header>"
export AI_CLOUD_PROJECT_ID="<project-id>"

curl -sS \
  -H "${AI_CLOUD_AUTH_HEADER}" \
  -H "X-Project-ID: ${AI_CLOUD_PROJECT_ID}" \
  "${AI_CLOUD_API}/api/v1/projects"

Retryable mutations should include an idempotency key.

curl -sS -X POST \
  -H "${AI_CLOUD_AUTH_HEADER}" \
  -H "X-Project-ID: ${AI_CLOUD_PROJECT_ID}" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"scheduler_type":"bare_metal"}' \
  "${AI_CLOUD_API}/api/v1/allocations"

Always inspect the returned state before retrying a mutation with different input.

SDK Authentication Pattern

SDKs should accept credentials from the host application or its secret manager. They should not read the CLI config file by default unless the SDK is explicitly building a local developer tool.

Recommended SDK inputs:

Input	Source
API base URL	environment config
Access token	identity provider, service-account flow, or user session handoff
Project ID	explicit application setting or user-selected project
Idempotency key	generated per retryable mutation

Keep token refresh, storage, and rotation owned by the application or platform identity layer. SDKs should avoid hidden credential discovery that makes automation hard to audit.

TypeScript Fetch Example

Generated SDK clients should follow the same contract. A direct fetch wrapper looks like this:

type AICloudClientOptions = {
  apiBase: string;
  sessionValue: string;
  projectId?: string;
};

function bearerAuthHeader(sessionValue: string) {
  return {'Authorization': ['Bearer', sessionValue].join(' ')};
}

export async function listProjects(options: AICloudClientOptions) {
  const response = await fetch(`${options.apiBase}/api/v1/projects`, {
    headers: {
      ...bearerAuthHeader(options.sessionValue),
      ...(options.projectId ? {'X-Project-ID': options.projectId} : {}),
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.code}: ${error.message} (${error.correlation_id})`);
  }

  return response.json();
}

For retryable mutations, add an idempotency key from the caller:

await fetch(`${apiBase}/api/v1/allocations`, {
  method: 'POST',
  headers: {
    ...bearerAuthHeader(sessionValue),
    'Content-Type': 'application/json',
    'X-Project-ID': projectId,
    'X-Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify(request),
});

Error Handling

Errors use stable codes and correlation IDs.

{
  "code": "validation_error",
  "message": "human-readable message",
  "correlation_id": "corr-example",
  "details": {}
}

Application code should:

• display or log the correlation ID;
• avoid logging tokens and secrets;
• branch on stable code values, not free-form messages;
• retry only when the operation is safe to retry;
• treat authorization and ownership errors as access problems, not transient API failures.

The CLI maps authentication failures to exit code 2, server-side failures to exit code 3, and other API errors to exit code 4. Automation should branch on exit code and the structured API error body, not on free-form console text.

WebSocket And Terminal Auth

Do not place tokens in query strings. Browser WebSocket auth uses the approved protocol boundary for terminal sessions. Normal REST integrations should use the Authorization header.

SDK Readiness Checklist

Before handing an SDK or automation to users:

1. Auth flow is documented.
2. Project context is explicit.
3. Idempotency is used for retryable mutations.
4. Structured errors are surfaced with correlation IDs.
5. Release or cleanup path is tested.
6. No token, key, cookie, or one-time code is logged.

Next

• Developer APIs
• App Developer Guide
• Launch Compute