Skip to main content
Guide
Sign in to Helix Cloud, link a project to a Cloud database, and query it. You need a Helix Cloud account and a database: see Get started with Helix Cloud, or create one from the CLI as in Move a local project to Helix Cloud.
1

Authenticate with WorkOS

Login needs an interactive terminal. On a remote machine over SSH, see Log in over SSH.
2

Link a project and database

The CLI picks your workspace, project, and database (the only one of each, or asks) and writes the project and a production database link to helix.toml. Link another database later with helix add cloud --name <name>.
3

Run a query through the broker

helix init cloud writes no example request. -e needs Node.js 20+ and npm; for JSON, pass a request file with --file.
4

Inspect the linked resources

Inside a linked project, Cloud commands default to its project and databases.
To use a different resource, pass it by ID, slug, or name after the subcommand, for example helix database list --project <project> or helix query tenant:<id> --file request.json. With --json, commands never prompt. See Cloud resource resolution.

Move a local project to Helix Cloud

Starting from a project created with helix init local:
1

Create and link a Cloud project

--link writes [project] id and workspace_id to helix.toml and keeps the local instances. For an existing Cloud project, run helix project link <project> instead.
2

Create a database

Creates a tenant database in the linked project and prints its default read-write application key once on stdout; store it in a secrets manager. A shared database needs --plan (prompted in a terminal); list codes with helix api get /v1/workspace-plans. For a dedicated cluster, pass --cluster <cluster> instead.
3

Add it to helix.toml

Writes an [enterprise.production] table with the database’s tenant:<id> target.
4

Query it

The Cloud database starts empty; the CLI does not copy local data. Replay your writes against production.
5

Connect your application

Applications call the database’s gateway with an application key, not the CLI session. helix database get orders --json prints the gateway host as connectionEndpoint. Create more keys with helix database key create --access read-only or read-write. See Connect to Helix Cloud and HTTP API authentication.

How Cloud queries are authorized

  • helix auth login creates a WorkOS session that identifies you, using GitHub, Google, Microsoft, single sign-on, or an email and password. 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 need database.query.read and writes database.query.write, granted on the project that owns the database. Project-management access does not imply query access.
  • Owners and admins have both query permissions 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 services to call the gateway directly.
  • helix service-credential manages credentials for headless agents on the MCP endpoint, limited to their project grants and without Cloud discovery or observability tools.
Neither logs the CLI in, so its Cloud commands cannot run unattended. See Run in CI for what CI can use instead.

Next steps

CLI configuration

How helix.toml stores project and database links.

helix query

Request formats and Cloud query behavior.

Scripting and CI

JSON output, exit codes, and unattended use.

helix database

Databases and application keys.