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
2
Link a project and database
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
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 withhelix 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
--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
[enterprise.production] table with the database’s tenant:<id> target.4
Query it
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 logincreates 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.readand writesdatabase.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 keycreates application keys for your services to call the gateway directly.helix service-credentialmanages credentials for headless agents on the MCP endpoint, limited to their project grants and without Cloud discovery or observability tools.
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.