Configuration

Croud stores user-specific data (such as authentication tokens, profiles, and settings) in a configuration file on disk to persist across sessions.

📁 Location

The configuration file is located inside your system's user-specific config directory. On Linux, for example, the path is:

$HOME/.config/Crate/croud.yaml

Croud uses the platformdirs Python package to determine the correct config directory for your operating system.

🧾 File Format

The configuration file is in YAML format. A default configuration might look like this:

current-profile: aks1.westeurope.azure
default-format: table
profiles:
  cratedb.cloud:
    auth-token: NULL
    key: NULL
    secret: NULL
    endpoint: https://console.cratedb.cloud
    region: _any_

🔑 Configuration Keys

Here’s what each key means:

Top-Level Keys

• current-profile The active profile to use for API requests. This must match one of the entries under profiles.

• default-format Default output format if a profile doesn't define one. Valid values:

  • table – (default) most relevant fields

  • wide – all fields in table format

  • json

  • yaml

Profile Keys (profiles.<profile-name>)

Each profile includes the following settings:

Key	Description
auth-token	Set automatically on login. Takes precedence over key/secret.
key	Optional. API key for headless authentication.
secret	Secret corresponding to the API key.
endpoint	The CrateDB Cloud API endpoint URL (e.g. https://console.cratedb.cloud).
region	The CrateDB Cloud region to use (e.g. westeurope.azure).
format	Optional. Output format for this profile (overrides default-format).

Note: If both auth-token and key/secret are present, auth-token takes precedence. To force key-based auth, explicitly set auth-token: NULL.

🔧 Manage Configuration via CLI

You can manage your configuration and profiles using the following commands:

croud config show
croud config profiles

Refer to the Config Command Reference for more details.

🤖 Headless Authentication (No Config File)

In environments where no croud.yaml exists (e.g., CI pipelines), you can authenticate using environment variables:

export CRATEDB_CLOUD_API_KEY=your-api-key
export CRATEDB_CLOUD_API_SECRET=your-secret