Skip to main content

​
Configuration Model

kdx has two configuration layers:
LayerUsed byPurpose
CLI profilesMost interactive commandsStore a platform URL, API key, and production-safety flag in ~/.kodexa/config.yaml
Sync environmentskdx sync workflowsResolve deployment environments from sync-config.yaml, usually with API keys read from environment variables
Profiles are still the normal way to use the CLI interactively. Sync environments are the preferred way to run repeatable GitOps deployments because the environment, target, and credential variable are declared with the metadata repository.

​
Browser Login

Use browser login when your environment supports CLI token exchange: 
kdx login https://app.kodexa.com --profile dev
Flags:
FlagDescription
--profileProfile name to save. If omitted, the CLI suggests one from the host name.
--timeoutSeconds to wait for login. Default is 180.
--no-browserPrint the login URL instead of opening a browser.
--deviceUse device-code login instead of a local browser callback.
Device-code login is useful for SSH sessions and CI-like terminals where a browser cannot open locally: 
kdx login https://app.kodexa.com --profile dev --device

​
API Key Profiles

Create or update a profile: 
kdx config set-profile dev \
  --url https://app.kodexa.com \
  --api-key <api-key>
Create a production profile with confirmation prompts enabled: 
kdx config set-profile prod \
  --url https://platform.kodexa-enterprise.com \
  --api-key <api-key> \
  --production
Manage profiles: 
kdx config list-profiles
kdx config current-profile
kdx config use-profile prod
kdx config delete-profile old-dev
list-profiles also accepts the alias get-profiles.

​
Command-Line Overrides

For a single command, override the current profile: 
kdx get projects --profile prod
For automation where you do not want to write a profile file, pass both URL and API key: 
kdx get projects \
  --url https://app.kodexa.com \
  --api-key "$KODEXA_API_KEY" \
  -o json
The general interactive CLI does not implicitly read a global KODEXA_API_KEY. Use profiles or explicit --url and --api-key overrides. kdx sync can read environment variables through sync-config.yaml.

​
Sync Environment Credentials

kdx sync resolves environments from sync-config.yaml: 
schema_version: "2"
environments:
  dev:
    url: https://dev.kodexa.com
    api_key_env: KODEXA_DEV_API_KEY
    api_version: v2
  prod:
    url: https://platform.kodexa-enterprise.com
    api_key_env: KODEXA_PROD_API_KEY
    api_version: v2
targets:
  finance:
    organization: acme-finance
    manifests:
      - manifests/finance.yaml
Then run: 
export KODEXA_DEV_API_KEY=<dev-key>
kdx sync pull --target finance --env dev

export KODEXA_PROD_API_KEY=<prod-key>
kdx sync deploy --target finance --env prod --dry-run
Environment entries can also reference a profile: 
environments:
  dev:
    profile: dev
    api_version: v2
Use api_key_env for CI/CD and profile for local development when you already have a saved profile.

​
Production Safeguards

Profiles marked with --production trigger confirmation before mutating commands such as apply and delete. 
kdx config set-profile prod \
  --url https://platform.kodexa-enterprise.com \
  --api-key <api-key> \
  --production
For non-interactive automation where the workflow itself provides approval, use: 
kdx apply -f resources/activity-plans/invoice-intake.yaml \
  --profile prod \
  --skip-production-confirm
Use this only in controlled automation. The bypass is logged.

​
File Locations

File or directoryPurpose
~/.kodexa/config.yamlSaved profiles and active profile
~/.kodexa/cache/Cached OpenAPI specifications and discovery metadata
sync-config.yamlGitOps environments, targets, branch mappings, and tag mappings
.sync-state/Sync conflict state. Commit this directory with the metadata repository.

​
Security Practices

  • Do not commit ~/.kodexa/config.yaml.
  • Prefer environment-backed sync credentials in CI/CD.
  • Use environment-specific API keys.
  • Mark production profiles with --production.
  • Rotate API keys regularly.
  • Use kdx secret set for organization secrets so secret values do not appear in command history.

​
Troubleshooting

​
No Active Profile

Create or select a profile: 
kdx config set-profile dev --url https://app.kodexa.com --api-key <api-key>
kdx config use-profile dev

​
Profile Not Found

List profiles and rerun the command with an existing name: 
kdx config list-profiles
kdx get projects --profile dev

​
Resource Cache Is Stale

Refresh discovery: 
kdx api-resources --refresh

​
Sync Cannot Resolve An Environment

Check that the environment is declared in sync-config.yaml and that its API key environment variable is set: 
env | grep KODEXA
kdx sync pull --target finance --env dev --dry-run