| Mode | Scope and capabilities | Storage |
|---|---|---|
| Browser OAuth | User identity, read-only Cloud operations and SQL | ~/.clickhouse/tokens.json, shared across directories |
| API key | Organization-scoped; writes and reads depend on assigned roles | .clickhouse/credentials.json in the project root when saved, found from any subdirectory |
clickhousectl cloud auth signup
clickhousectl cloud auth login
clickhousectl cloud auth login --interactive
clickhousectl cloud auth whoami
clickhousectl cloud auth statussignup opens account creation. Plain login opens the OAuth device flow; in JSON mode its code and URL go to stderr, so stdout holds only the login report. --interactive prompts for an API key and secret; it needs a TTY and cannot be combined with --api-key or --api-secret (both exit 2). Login checks identity: a rejected key is not saved and exits 4. If the API is unreachable, the key is saved with a warning for offline setup. whoami requires no organization selection and supports either credential type.
auth status shows configured sources, the active source, and identity verification. It can exit 0 with no active credentials, rejected credentials, or an unavailable identity check; use whoami or the intended command to test access. Its remote check times out after five seconds.
If a saved OAuth login cannot be read or uses an older format without complete authorization configuration, auth status shows OAuth as Login required, not Not configured, and explains the problem below the table with the command to log in again. JSON output includes this explanation in oauth_warning, separate from any identity-verification warning; it is shown even when an API key is active. Run clickhousectl cloud auth login to log in again. Without a higher-priority API key source, Cloud commands exit 4 (auth_required in JSON) with an explicit re-login message. The unusable file is left unchanged; the CLI does not reconstruct its authorization configuration from built-in defaults or environment variables.
cloud service client is the exception to both modes for SQL: either credential only looks up the service, and clickhouse client --login then signs you in to the service itself through its own browser flow, as your Cloud user. That needs a person at a browser, so it does not suit CI or agents. See Open an interactive client.
For automation, inject CLICKHOUSE_CLOUD_API_KEY and CLICKHOUSE_CLOUD_API_SECRET through a secret manager. The CLI does not save environment credentials. For development it also reads .env from the current directory or, when that has none, from the project root; the first file found is used alone, never merged. Keep that file out of version control and restrict access. Flags are available, but command-line secrets can appear in shell history and process listings.
The first applicable source wins:
--api-keyand--api-secretflags..clickhouse/credentials.jsonin the project root.- Exported environment variables.
- Variables loaded from
.envin the current directory, else in the project root. - Global OAuth tokens.
Supplying only one credential flag blocks fallback. So does a .clickhouse/credentials.json that exists but cannot be read or parsed: Cloud commands exit 1 with an error naming the file instead of using environment or OAuth credentials, and auth status shows the API key source as Unreadable with the error below the table (credentials_warning in JSON). Fix the file, or remove it with clickhousectl cloud auth logout --api-keys. Cloud commands skip OAuth token refresh when a higher-priority API key source wins, leaving saved OAuth tokens unchanged. When OAuth is selected, expired or near-expiry tokens are refreshed before the API request. If the login has no refresh token or the refresh fails, including when the authorization server is unreachable, the saved login is kept: auth status shows OAuth as Expired, and the command exits 4 (auth_required in JSON) with a message to run clickhousectl cloud auth login. auth status identifies inactive sources; --debug on a Cloud command prints the selected credential source and API URL to stderr.
A saved API key works only against the API it was saved for. When auth login --api-key verifies a key against a non-production API (--url), that API is saved with the key as api_url; a key with no api_url is for production. Later commands without --url use the saved API, print a note naming it to stderr, and derive the Query API host for cloud service query from it unless CLICKHOUSE_CLOUD_QUERY_HOST is set. A --url naming any other API exits 4 without sending the key or falling back to environment or OAuth credentials: pass the saved URL, or save a key for that API. auth status shows the API each saved source uses. Flag and environment keys carry no URL; they use --url or production.
cloud postgres query accepts OAuth only, unlike cloud service query. Remove higher-priority API key sources before using that route. Clearing a saved key file alone is insufficient if exported variables or .env still supply a key.
clickhousectl cloud org list
clickhousectl cloud service list --org-id <org-id>
clickhousectl cloud service get --name analytics --org-id <org-id>Organization-scoped commands auto-select only when credentials reach exactly one organization. Otherwise pass --org-id or, where supported, exact --org-name. When credentials reach several organizations and neither is given, the command exits 2 as a usage error and lists each organization's ID and name. Organization names need not be unique: when --org-name matches more than one, the command exits 1 and lists the matching IDs to pass to --org-id.
Most resource commands accept a positional ID or exact --name. Name lookup needs list permission within the selected organization or required parent service, and ambiguous matches fail. A child name selects the child, never its parent service. Member and invitation --email matching is exact, including case.
Every executable Cloud command's --help lists bundled API-key permission requirements without making a network request:
clickhousectl cloud service get --help
clickhousectl cloud service query --helpAll applicable permissions are needed, including conditional permissions for name lookup, optional flags, and Query API binding. An empty upstream permission list still requires a valid key. Permission help does not inspect your credentials, change OAuth's read-only restriction, or grant SQL privileges.
Schema discovery for ClickPipes requires an API key. Postgres query is OAuth-only. See Query API behavior for ClickHouse SQL and key administration for key roles and IP allowlists.
Find a role appropriate for the intended commands, then create a key with an explicit trusted egress IP/CIDR and expiration:
clickhousectl cloud org role list --org-id <org-id>
clickhousectl cloud key create --org-id <org-id> --name ci-key \
--role-id <role-id> --expires-at <future-RFC3339-time> \
--ip-allow '203.0.113.10/32=CI runner'Replace the example IP. Omitting --ip-allow on key creation denies all network access, unlike service creation's allow-all default. Use 0.0.0.0/0 only for deliberately unrestricted access.
Save the generated authentication key ID and secret securely; the secret is returned only at creation. The management resource id used by get, update, delete, and endpoint bindings differs from the authentication keyId/keySecret. Pre-hashed key creation does not return a secret.
clickhousectl cloud key list --all --json
clickhousectl cloud key get <key-id>
clickhousectl cloud key update <key-id> --state disabledWithout --all, list returns one page. --limit is at least 1 and --cursor takes the opaque nextCursor unchanged. One-page JSON has a result array and optional metadata; only an absent nextCursor marks the last page (an empty string is still a token). --all --json combines pages into one array and emits no partial array on failure; it conflicts with --cursor. Name selectors search every page and reject ambiguity.
Omitting expiry, role, or IP flags on update preserves that setting. --clear-expiry, --clear-roles, and --clear-ip-allow deliberately remove it and conflict with the corresponding set flag. Clearing the IP list denies all network access. After disabling/deleting a key, inspect dependent automation and Query API bindings; do not rotate keys automatically to bypass an administrator's restriction.
clickhousectl cloud member list
clickhousectl cloud member update <user-id> --role-id <role-id>
clickhousectl cloud invitation create --email dev@example.com --role-id <role-id>Member/invitation email selectors match exactly, including case. Omitting member role flags preserves assignments; --clear-roles removes all and conflicts with --role-id.
Member notification settings (Beta) are a member's own overrides of their role's defaults; an empty list means the defaults apply, not that notifications are off. list returns one page with the same result/limit/nextCursor contract as org notifications. update takes either one rule from flags or a whole request body from --file (- for stdin), never both. A rule applies its --effect to every combination of its --notification types, --resource IDs and --channel values (every channel when omitted); inherit removes the override. Resources must be named one by one, using the organization ID for organization-level types such as billing. The server applies a request completely or not at all:
clickhousectl cloud member notification-settings list <user-id> --type service_backup_failed
clickhousectl cloud member notification-settings update <user-id> --effect disabled \
--notification service_backup_failed --resource <service-id> --channel email
clickhousectl cloud member notification-settings update --email dev@example.com --file rules.jsonCustom organization roles are created/updated with --file (- for stdin). Updates are partial at the root, but supplied actors and policies replace their complete lists. Only custom roles can be updated/deleted. Policy allowDeny is ALLOW or DENY; SQL roleV2 values are sql-console-readonly or sql-console-admin. Inspect org role get and prepare a writable request without unrelated response fields.
clickhousectl cloud org notification-types --org-id <org-id>
clickhousectl cloud org notifications --org-id <org-id> --severity warning \
--from-date 2026-10-01T00:00:00Z --limit 100 --json
clickhousectl cloud org notifications --org-id <org-id> --cursor '<nextCursor>' --jsonNotifications are Beta and support OAuth reads. Each invocation returns one page; JSON contains result and optional limit/nextCursor. Pass the cursor unchanged until it is absent; an empty string is still a cursor. Keep the same filters across pages. --limit accepts 1–250; omission uses the server default of 100. Results are retained for 180 days and include only resources the caller can access.
Use --type with a name from notification-types, --severity, --resource-id, or --resource-type to narrow results. A service ID also matches its ClickPipes unless a resource kind narrows it. --from-date and --to-date are inclusive RFC 3339 timestamps. Human output shows a table and the next cursor as a JSON string; JSON preserves notification descriptions and resource names too.
Use cloud org --help for quotas, credit balance, notifications, notification types, preview features, usage, settings, BYOC infrastructure, and Prometheus discovery. org preview list shows each preview feature's ID, whether it is on and whether you can switch it; org preview update <preview-id> --enabled true|false switches it, and only a feature offered to the organization can be turned on. BYOC validate is a preflight that creates nothing but requires an API key. Creation is asynchronous: find infrastructure IDs in org get's byocConfig, then inspect byoc get and byoc progress before creating a service in it.
byoc update changes only the flags you pass. Its --tag flags replace the infrastructure's whole tag set, so read the current set with byoc tags first; byoc private-endpoint-config shows the private link endpoint service to connect to:
clickhousectl cloud org byoc tags <byoc-id>
clickhousectl cloud org byoc update <byoc-id> --tag team=data --tag env=prod
clickhousectl cloud org byoc update <byoc-id> --enable-private-link true
clickhousectl cloud org byoc private-endpoint-config <byoc-id>byoc access (Beta) controls when ClickHouse personnel may access the infrastructure. update replaces the whole setting: --mode always allows access, --mode never denies it, and --mode window allows it for --duration seconds from --start, which that mode requires and the others reject. The response's allowed is the data plane's verdict at request time:
clickhousectl cloud org byoc access get <byoc-id>
clickhousectl cloud org byoc access update <byoc-id> --mode window \
--start 2026-11-10T09:00:00Z --duration 14400BYO-VPC --vpc-id needs --private-subnet-id and conflicts with --vpc-cidr-range. For private endpoint registration, use the provider's endpoint identity, not an endpoint-service name or ARN; registration affects the organization as well as the service. Removing an organization endpoint requires both provider and region to identify it completely. The CLI's format checks do not prove an endpoint exists or belongs to you.
clickhousectl cloud auth logout --oauth
clickhousectl cloud auth logout --api-keys
clickhousectl cloud auth logoutThe last command clears both saved credential types. It does not unset environment variables or remove .env values. Clearing API keys deletes the entire local credentials file, including any per-service Query API key records left by earlier versions. Those keys still exist in the organization; find them with cloud key list (named clickhousectl-query-<service-name>) and delete them with cloud key delete <key-id>. See keys stored by earlier versions.