> ## Documentation Index
> Fetch the complete documentation index at: https://helix-isolate-failing-index-entities.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Helix Cloud CLI workflow

> Authenticate, link, query, and manage Cloud resources

<div className="flex flex-wrap gap-2"><Badge color="blue" size="sm">Guide</Badge></div>

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](/database/helix-cloud/start-here/using-the-cloud).

<Steps>
  <Step title="Authenticate with WorkOS">
    ```bash theme={null}
    helix auth login
    helix auth status
    ```
  </Step>

  <Step title="Link a project and database">
    ```bash theme={null}
    helix init cloud
    ```

    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>`.
  </Step>

  <Step title="Run a query through the broker">
    ```bash theme={null}
    helix query production --file request.json
    helix shell production
    ```
  </Step>

  <Step title="Inspect the linked resources">
    ```bash theme={null}
    helix status
    helix database
    helix logs production
    ```

    Inside a linked project, Cloud commands default to its project and databases, so
    they need no IDs.
  </Step>
</Steps>

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](/cli/command-reference#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

<CardGroup cols={2}>
  <Card title="CLI configuration" icon="gear" href="/cli/configuration">
    How `helix.toml` stores project and database links.
  </Card>

  <Card title="helix query" icon="terminal" href="/cli/command-reference/query">
    Request formats and Cloud query behavior.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.