Helix Cloud CLI workflow

Authenticate, link, query, and manage Cloud resources

Guide

1. Authenticate with WorkOS

   helix auth login
   helix auth status
   
2. Discover a target

   helix workspace list
   helix project list --workspace-id <workspace-id>
   helix database list --project <project-id>
   
3. Link the current project and database

   helix project link <project-id>
   helix add cloud --name production --database tenant:<tenant-id>
   
4. Run a query through the broker

   helix query production --file request.json
   helix shell production
   

The WorkOS session identifies the user. database.query.read or database.query.write independently authorizes the selected database; project-management access does not imply query access. The backend forwards the authorized request using the existing cluster-scoped operational gateway key and, for a tenant database, the exact tenant header. The CLI never receives that key and never contacts the gateway directly.

Owners/admins have both query scopes by default. Members have neither unless explicitly granted. Local queries keep the current local auth-disabled path.

Use helix database key only to create application keys for direct gateway clients. Use helix service-credential only to manage headless API/MCP credentials. Neither is a CLI login method.