CLI configuration

Project linkage and WorkOS session files

Reference

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

[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.