Skip to main content
Guide
Use the CLI to sign in to Helix Cloud, link a project to a Cloud database, and run queries against it. You need a Helix Cloud account and at least one database; see Get started with Helix Cloud.
1

Authenticate with WorkOS

2

Link a project and database

The CLI picks your workspace, project, and database: it uses the only one of each or asks you to choose. It writes the project and a production database link to helix.toml. To link another database later, run helix add cloud --name <name>.
3

Run a query through the broker

4

Inspect the linked resources

Inside a linked project, Cloud commands default to its project and databases, so they need no IDs.
Pass a resource by ID, slug, or name when you want a different one, for example helix database list --project <project> or helix query tenant:<id> --file request.json. In scripts, add --json for machine-readable output; commands then never prompt. See Cloud resource resolution.

​
How Cloud queries are authorized

  • helix auth login creates a WorkOS session that identifies you. The CLI never uses database API keys.
  • Cloud queries go through the Helix Cloud backend (the broker), not directly to the database gateway. The broker forwards each authorized request with its own gateway credentials, which the CLI never receives.
  • Reads require the database.query.read scope and writes require database.query.write on the selected database. Project-management access does not imply query access.
  • Owners and admins have both query scopes by default. Members have neither unless explicitly granted.
  • Local queries are unaffected and run without authentication.

​
Keys and credentials are not logins

  • helix database key creates application keys for your own services that call the gateway directly.
  • helix service-credential manages headless HTTP API and unified MCP credentials. MCP tool access follows the credential’s project grants, and these sessions do not get Cloud discovery or observability tools.
Neither can be used to sign in to the CLI.

​
Next steps

CLI configuration

How helix.toml stores project and database links.

helix query

Request formats and Cloud query behavior.