Profiles & Configuration - Kodexa Developer Portal

Configuration Model

kdx has two configuration layers:

Layer	Used by	Purpose
CLI profiles	Most interactive commands	Store a platform URL, API key, and production-safety flag in `~/.kodexa/config.yaml`
Sync environments	`kdx sync` workflows	Resolve 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. Use browser login when your environment supports CLI token exchange:

kdx login https://app.kodexa.com --profile dev

Flags:

Flag	Description
`--profile`	Profile name to save. If omitted, the CLI suggests one from the host name.
`--timeout`	Seconds to wait for login. Default is `180`.
`--no-browser`	Print the login URL instead of opening a browser.
`--device`	Use 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 directory	Purpose
`~/.kodexa/config.yaml`	Saved profiles and active profile
`~/.kodexa/cache/`	Cached OpenAPI specifications and discovery metadata
`sync-config.yaml`	GitOps 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

​Configuration Model

​Browser Login

​API Key Profiles

​Command-Line Overrides

​Sync Environment Credentials

​Production Safeguards

​File Locations

​Security Practices

​Troubleshooting

​No Active Profile

​Profile Not Found

​Resource Cache Is Stale

​Sync Cannot Resolve An Environment