Configuration

cx stores all configuration under ~/.cx/.

Directory structure

~/.cx/
  config.toml              # Global settings
  profiles/
    default.toml           # Default profile
    prod.toml              # Named profile
    staging.toml           # Named profile

Quick start

Run cx profiles add to create or update the default profile. OAuth (browser login) is selected by default and is the recommended option — it opens your browser, captures the callback automatically, and stores tokens securely in the OS keyring.

$ cx profiles add
Configuring profile 'default'

Authentication method: OAuth (browser login)
Region: eu2
Label (e.g. 'prod'): production

Opening browser for authentication...
Waiting for browser callback...
Authorization code received, exchanging for tokens...
Login successful!

Profile 'default' saved to /Users/you/.cx
Credentials stored in OS credential store (OAuth tokens)

To use a plain API key instead, select API key (paste manually) at the first prompt. The API key must be a Team Key or a Personal Key — see API Key below for where to generate one. Send-Your-Data / ingress keys will not work for querying.

Authentication methods

OAuth (default)

OAuth uses the standard browser-based Authorization Code + PKCE flow.

• Tokens (access_token, refresh_token, id_token) are stored in the OS keyring and are never written to the profile TOML.
• The access token is silently refreshed on each cx invocation when it is within 30 seconds of expiry.
• If the refresh token is also expired, cx exits with an actionable message:

Run cx profiles add <name> to re-authenticate.

Custom or non-standard environments

If your environment is not in the standard region list, select Custom (specify URL + client ID) at the Region prompt:

Region: Custom (specify URL + client ID)
Base URL (e.g. https://api.myenv.coralogix.com): https://api.myenv.example.com
OAuth client ID: abc123-my-client

The base URL is used both as the API endpoint and for OpenID Connect discovery ({base_url}/oauth/.well-known/openid-configuration). The client ID is stored in the profile TOML (oauth_client_id) since there is no built-in mapping for it.

API key

A static Coralogix API key. The key must be one of the following types — cx uses it as a Bearer token when calling the query APIs, so ingress ("Send-Your-Data") keys will not work:

• Team Key — generated in the Coralogix UI under Data Flow → API Keys → Team Keys. Scoped to a team; typical choice for shared/CI usage.
• Personal Key — generated in the Coralogix UI under the user menu (top-right) → Personal Keys. Scoped to your user account.

The key can be stored either in the profile TOML file (permissions set to 0600 on Unix) or in the OS keyring.

OS keyring backends

Credentials stored in the OS keyring use the following backends:

Platform	Backend
macOS	Keychain
Windows	Credential Manager
Linux (glibc)	D-Bus Secret Service (GNOME Keyring, KWallet)
Linux (musl)	No keyring backend — fall back to file-based storage

The default install script and release binaries are built for musl on Linux, so keyring support is only available when you build from source against glibc. Script-installed Linux users must use file-based credential storage.

Global config (~/.cx/config.toml)

Example:

default_profile = "default"
default_output_format = "text"
max_dataprime_direct_output_size = 102400
temp_dir = "/tmp/"

Profile files (~/.cx/profiles/<name>.toml)

Each profile stores credentials and endpoint configuration. Sensitive secrets (API key, OAuth tokens) live in the OS keyring when credential_storage = "os_store" and are not written to the TOML.

Common fields

OAuth-specific fields

Example: OAuth profile (known region)

auth = "oauth"
credential_storage = "os_store"
region = "eu2"
label = "production"

Tokens live in the OS keyring; nothing sensitive is in this file.

Example: OAuth profile (custom environment)

auth = "oauth"
credential_storage = "os_store"
region = "https://api.myenv.example.com"
oauth_client_id = "abc123-my-client"
label = "custom-env"

Example: API key profile (OS keyring)

auth = "api_key"
credential_storage = "os_store"
region = "eu1"
label = "production"

The API key is stored in the OS keyring under service cx-cli, profile name as the account.

Example: API key profile (file, legacy)

region = "eu1"
api_key = "cxp_your_api_key_here"
label = "production"

Legacy profiles without an auth field behave as auth = "api_key" automatically.

Regions

A fully qualified HTTPS URL can be used as a region value for non-standard environments.

Environment variables

Environment variables override profile file values:

Variable	Overrides
CX_PROFILE	-p flag / default_profile
CX_API_KEY	api_key in profile (also overrides OAuth — sets the bearer token directly)
CX_REGION	region in profile

Precedence order: CLI flags > environment variables > profile file > global config defaults.

Note: CX_API_KEY / --api-key always win, even for OAuth profiles. This lets scripts and CI systems inject tokens directly without going through the browser login flow.

Env-only mode: when no profile file exists on disk but both CX_API_KEY (or --api-key) and CX_REGION (or --region) are supplied, cx runs without a profile file. This is convenient for ephemeral environments (CI runners, containers, ad-hoc scripts) where running cx profiles add first would be a paper-cut.

Shell completion and profiles

Profile names discovered in ~/.cx/profiles/*.toml are offered as tab-completion candidates for the -p/--profile flag and for the profiles add, profiles delete, and profiles set-default subcommands.

When using static completions installed with cx completions install, profile names are captured at installation time. After adding or deleting a profile, cx will print a reminder to run cx completions refresh, which regenerates every file registered in managed_completions.

The managed_completions field in ~/.cx/config.toml is updated automatically by cx completions install and is read by cx completions refresh. Only files recorded here are ever modified by cx; files installed by cx completions generate ... > /path are not tracked.

For profile names that are always resolved fresh without a manual refresh step, use the dynamic completion approach instead: source <(COMPLETE=zsh cx) (or the bash/fish equivalent). See the Shell completions section in the README for full setup instructions.

OAuth callback ports

The local HTTP callback listener used during cx profiles add (OAuth path) binds one port from the following fixed allow-list, chosen at random:

21783  24861  27654  31847  38129

Ensure at least one of these ports is available when running cx profiles add.