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 <name> to create a new profile or update an existing one:

cx profiles add <name>

At the prompts:

1. Authentication method — OAuth (browser login) (recommended) opens your browser and stores tokens securely. Select API key (paste manually) to use a static key instead.
2. Region — your Coralogix region (e.g. eu2, us1). See Regions for the full list.
3. Label — an optional tag to group or identify profiles (e.g. production).
4. Credential storage — file (default) saves credentials in the profile TOML; os-store uses the OS keyring (macOS Keychain, Windows Credential Manager, or D-Bus Secret Service on Linux).

If using an API key, it must be a Team Key or Personal Key. Send-Your-Data / ingress keys will not work.

Authentication methods

OAuth (default)

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

• Tokens (access_token, refresh_token, id_token) are persisted using the chosen credential_storage backend - either inline in the profile TOML (file, the default) or in the OS keyring (os_store).

• The access token is silently refreshed on each cx invocation when it is within 30 seconds of expiry. The refreshed token set is written back to the same backend.

• 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 (BYOC / private-link)

If your environment is not in the standard region list, choose Custom endpoint (BYOC / private link) at the Region prompt:

Region: Custom endpoint (BYOC / private link)
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.

Don't know your region? Paste your URL

If you're not sure which region you're in, choose Paste a Coralogix URL at the Region prompt and paste the URL from your browser (e.g. https://myteam.app.eu2.coralogix.com). cx recognises the Coralogix app and API domains and derives the region for you:

URL you paste	Derived region
https://<team>.app.coralogix.us	us1
https://<team>.app.cx498.coralogix.com	us2
https://<team>.app.us3.coralogix.com	us3
https://<team>.coralogix.com	eu1
https://<team>.app.eu2.coralogix.com	eu2
https://<team>.app.coralogix.in	ap1
https://<team>.app.coralogixsg.com	ap2
https://<team>.app.ap3.coralogix.com	ap3

A URL that doesn't match a known Coralogix domain (a bring-your-own-cloud deployment, private-link, or custom domain) falls back to manual endpoint entry rather than erroring out.

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)

Key	Default	Description
default_profile	"default"	Profile used when -p is not provided
default_output_format	"text"	Output format when -o is not provided (text, json, toon; agents accepted as a deprecated alias)
max_dataprime_direct_output_size	102400 (100 KiB)	Max byte size for non-aggregated DataPrime results in toon mode before spilling to a temp file. Set to -1 to disable
temp_dir	"/tmp/"	Directory for spilled result files
read_only	false	Block all write operations globally (equivalent to always passing --read-only)
no_console_link	false	Suppress "View in Coralogix" console links globally (equivalent to always passing --no-console-link)
allow_risky_commands	true	Allow write operations under risky commands (iam, archive)
olly_enabled	true	Enable the Olly AI assistant (olly ask)

Example:

default_profile = "default"
default_output_format = "text"
max_dataprime_direct_output_size = 102400
temp_dir = "/tmp/"
read_only = false
no_console_link = false
allow_risky_commands = true
olly_enabled = true

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

Each profile stores credentials and endpoint configuration. credential_storage selects where secrets live for both auth modes: with "file" (the default) the API key or OAuth token set is written inline in the TOML (0600 perms on Unix); with "os_store" the secrets live in the OS keyring and the inline fields are absent.

Common fields

Key	Required	Description
auth	No	"oauth" or "api_key" (default "api_key" for backward compatibility)
region	Yes	Coralogix region identifier or a custom URL (see below)
credential_storage	No	"file" or "os_store" (default "file")
label	No	Free-form label, for example "production"
console_url	No	Overrides the web console base URL used to build "View in Coralogix" links. If unset, cx resolves it automatically via GET /identity/whoami - see Console links.

OAuth-specific fields

Key	When present	Description
oauth_client_id	Custom environments	OAuth client ID. Omitted for known regions (hard-coded in the binary).
oauth_base_url	Rarely	Overrides the base URL for OpenID discovery. Defaults to region.api_endpoint().
oauth_tokens	credential_storage = "file"	Cached access/refresh/id tokens and expiry. Absent when tokens live in the OS keyring.

Example: OAuth profile (known region, file storage - default)

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

[oauth_tokens]
access_token = "..."
refresh_token = "..."
expiry = 1700000000

The token set is rewritten in place each time cx refreshes. The file is created with 0600 permissions on Unix.

Example: OAuth profile (known region, OS keyring)

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 = "file"
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

Region	Endpoint
us1	https://api.us1.coralogix.com
us2	https://api.us2.coralogix.com
us3	https://api.us3.coralogix.com
eu1	https://api.eu1.coralogix.com
eu2	https://api.eu2.coralogix.com
ap1	https://api.ap1.coralogix.com
ap2	https://api.ap2.coralogix.com
ap3	https://api.ap3.coralogix.com

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

Console links

After a successful command on entities with a corresponding web console page, cx prints a View in Coralogix: <url> line to stderr. The console base URL used to build these links is resolved in this order:

1. console_url in the profile TOML, if set - used as-is (see the field table above). No API call is made when this is set.
2. Otherwise, a fresh cached team_url in the profile TOML. The first time cx resolves a team's console URL (step 3) it writes the result back to the profile file as a machine-managed cached_console_url (with a cached_console_url_at timestamp), the same way OAuth tokens are cached there. Subsequent invocations reuse it for 7 days, so agents making many sequential calls don't pay a GET /identity/whoami round-trip on every command. Env-only invocations (CX_API_KEY + CX_REGION with no profile file) have nowhere to cache and resolve live each process.
3. Otherwise, cx calls GET /identity/whoami and uses its team_url field verbatim, then caches it per step 2. This is the default on a cold cache - most teams don't need to configure anything to get console links.
4. No link is printed if /identity/whoami fails, or returns no usable team_url.

A failed or unusable /identity/whoami response in step 3 never fails the command - it just means no console link, exactly like step 4. When no link can be resolved, cx stays silent: no View in Coralogix line on stderr, and the command otherwise succeeds normally.

Set console_url explicitly in the profile TOML to override this, e.g. for a Custom region running a self-hosted console where /identity/whoami isn't reachable.

Disabling console links

The stderr View in Coralogix line can be suppressed entirely. This also skips the /identity/whoami lookup on a cold cache.

There are three ways to enable it, listed from narrowest to broadest scope:

Method	Scope	Example
--no-console-link flag	Single invocation	cx --no-console-link alerts list
CX_NO_CONSOLE_LINK env var	Shell session / CI job	export CX_NO_CONSOLE_LINK=true
no_console_link = true in ~/.cx/config.toml	All invocations	See global config table above

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
CX_READ_ONLY	read_only in global config (accepts 1, true, yes, on)
CX_NO_CONSOLE_LINK	no_console_link in global config (accepts 1, true, yes, on)
CX_TELEMETRY	Set to false, no, off, or 0 to disable CLI request metadata

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 <name> first would be a paper-cut.

Request metadata

Each authenticated Coralogix API request includes bounded X-Cx-Cli-* headers for the current invocation: command path and family, output format, authentication type, installed CX skills, selected and configured profile counts, and write-operation and --yes flags. X-Cx-Cli-Metadata also contains the same values as compact JSON. X-Cx-Cli-Installed-Skills is a sorted JSON list of installed skill directory names, without filesystem paths. It lists only the skills bundled with this cx version that are found installed. X-Cx-Cli-Is-Agent is true when the master agent-environment detector matches, and false otherwise.

The installation identifier is a random UUID stored in ~/.cx/state.json; it identifies a CLI installation, not a person or API key. Request metadata never includes API keys, profile names, command arguments, query text, raw error messages, arbitrary environment variables, outcome, error details, HTTP status, or duration.

Set CX_TELEMETRY=false to opt out of these headers entirely.

Read-only mode

Read-only mode blocks all write operations (create, update, delete, enable, disable, etc.) while allowing reads (list, get, query, search). This is useful for giving agents or automation safe, query-only access to your Coralogix data.

There are three ways to enable it, listed from narrowest to broadest scope:

Method	Scope	Example
--read-only flag	Single invocation	cx --read-only alerts list
CX_READ_ONLY env var	Shell session / CI job	export CX_READ_ONLY=true
read_only = true in ~/.cx/config.toml	All invocations	See global config table above

When a write operation is attempted in read-only mode, cx exits with an error:

Error: Write operation 'create' is blocked in read-only mode
(--read-only flag, CX_READ_ONLY env var, or read_only = true in ~/.cx/config.toml).

Local commands (profiles, cleanup, completions) are exempt from read-only enforcement - they manage local configuration and never touch the Coralogix API.

The env var accepts 1, true, yes, or on (case-insensitive).

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 <name> (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 <name>.