> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helix-db.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI configuration

> Project linkage and WorkOS session files

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

The CLI reads project configuration from `helix.toml` and its WorkOS session from
`~/.helix/credentials`. There is no user-global workspace selection file.

```toml theme={"languages":{"custom":["languages/helixql.json"]}}
[project]
name = "example"
queries = "db"
container_runtime = "docker"
id = "project_123"          # stable optional Cloud link
workspace_id = "ws_123"     # stable optional Cloud link

[local.dev]
port = 6969

[enterprise.production]
database = "tenant:tenant_123"
project_id = "project_123"  # optional stable link
workspace_id = "ws_123"     # optional stable link
```

Cloud `database` accepts only `tenant:<id>` or `cluster:<id>`. A physical shared cluster is not a
database target. Unknown Cloud fields are rejected. In particular, gateway URLs, query auth headers,
query auth environment variables, source snapshots, sync metadata, and query bundles are invalid.

Target resolution uses an explicit flag first, then an explicit database reference, the linked
database, or the linked project only when exactly one database is eligible. Ambiguous commands print
candidates and require `--workspace`, `--project`, `cluster:<id>`, or `tenant:<id>`.

The strict credential file stores only `access_token`, rotating `refresh_token`, `expires_at`, and
`email`. It is written atomically with mode `0600`. Do not edit it or put application keys or service
credentials in it.