Profiles & Configuration - Kodexa Developer Portal

Early AccessConfiguration file structure and profile management commands may evolve based on user feedback and security best practices.

Profiles are Deprecated in kdx sync v2Profile-based configuration is being phased out in favor of environment-based configuration. New kdx sync v2 features use environment variables and sync-config.yaml instead of profiles.For new projects, use the environment variable approach documented in Metadata Sync.For existing profile users, see the Migration Guide below to convert to the new approach.This documentation is maintained for legacy reference and users of older KDX CLI versions.

Migrating from Profiles to Environment Variables

The new v2 architecture uses environment variables instead of profiles for cleaner, more secure configuration.

Key Differences

Legacy (Profiles)	New (Environment Variables)
`~/.kodexa/config.yaml`	Environment variables + `sync-config.yaml`
`kdx config use-profile prod`	`export KODEXA_API_KEY=...`
Multiple profiles in one file	One environment per shell/CI job
`--profile` flag on commands	Environment variables auto-detected

Migration Steps

1. Extract credentials from profile:

# View your current profile settings
kdx config current-profile

2. Set environment variables:

# Add to ~/.bashrc, ~/.zshrc, or CI/CD configuration
export KODEXA_URL="https://platform.kodexa.ai"
export KODEXA_API_KEY="sk_your_api_key_here"

3. Configure sync targets in sync-config.yaml:

# sync-config.yaml (replaces profile selection)
version: 2
targets:
  - name: production
    org: my-org
    workspace: my-workspace
    description: Production environment

4. Use environment-specific API keys:

# Development
export KODEXA_API_KEY="sk_dev_key"

# Staging
export KODEXA_API_KEY="sk_staging_key"

# Production
export KODEXA_API_KEY="sk_prod_key"

5. Update scripts:

# OLD (profile-based)
kdx config use-profile prod
kdx sync push

# NEW (environment-based)
export KODEXA_API_KEY="sk_prod_key"
kdx sync push

Benefits of Environment Variables

Security:

No credentials in committed files
OS-level security for environment variables
Easier secret management in CI/CD

Simplicity:

One less config file to manage
Standard approach across tools
Natural fit for containerized environments

Flexibility:

Per-shell environment configuration
Easy integration with secret managers
Simpler CI/CD pipelines

For CI/CD Pipelines

OLD (profile-based):

- name: Deploy
  run: |
    kdx config set-profile prod --url $URL --api-key $KEY
    kdx sync push

NEW (environment-based):

- name: Deploy
  env:
    KODEXA_API_KEY: ${{ secrets.KODEXA_PROD_KEY }}
  run: |
    kdx sync push

Backwards Compatibility

Profile commands (kdx config) still work for legacy users
--profile flag continues to function
Gradual migration path available
Environment variables take precedence when both exist

Understanding Profiles (Legacy Reference)

Note: This section documents the legacy profile system. New users should use environment variables instead.

Profiles store connection details and credentials for different Kodexa environments. Each profile contains:

Platform URL - The base URL of your Kodexa instance
API Key - Authentication credentials
Name - A friendly identifier for the profile
Production Flag - Marks the environment as production for safety prompts

Profiles enable you to:

Switch seamlessly between environments (dev, staging, prod)
Manage multiple organizations or tenants
Share configuration templates with team members
Avoid hardcoding credentials in scripts
Protect production environments with confirmation prompts

Configuration File Location

All KDX CLI configuration is stored in:

~/.kodexa/config.yaml

The cache directory stores OpenAPI specifications:

~/.kodexa/cache/

Configuration File Structure

The config.yaml file has a simple structure:

currentProfile: prod
profiles:
  local:
    url: http://localhost:8080
    apiKey: sk_local_dev_key_example
  staging:
    url: https://staging.kodexa.ai
    apiKey: sk_staging_key_example
  prod:
    url: https://platform.kodexa.ai
    apiKey: sk_prod_key_example
    productionEnvironment: true

The configuration file is created automatically when you create your first profile.

Creating Profiles

Create a New Profile

Use the config set-profile command to create or update a profile:

kdx config set-profile prod \
  --url https://platform.kodexa.ai \
  --api-key sk_your_api_key_here

Create Multiple Profiles

Set up profiles for all your environments:

# Local development
kdx config set-profile local \
  --url http://localhost:8080 \
  --api-key sk_local_key

# Staging environment
kdx config set-profile staging \
  --url https://staging.kodexa.ai \
  --api-key sk_staging_key

# Production environment
kdx config set-profile prod \
  --url https://platform.kodexa.ai \
  --api-key sk_production_key \
  --production

Update an Existing Profile

Re-run set-profile with the same name to update:

# Update API key for production
kdx config set-profile prod \
  --url https://platform.kodexa.ai \
  --api-key sk_new_production_key

Managing Profiles

List All Profiles

View all configured profiles:

kdx config list-profiles

Example output:

NAME       URL                          PRODUCTION  CURRENT
local      http://localhost:8080        No
staging    https://staging.kodexa.ai    No
prod       https://platform.kodexa.ai   Yes         *

View Current Profile

Check which profile is currently active:

kdx config current-profile

Example output:

Current profile: prod
URL: https://platform.kodexa.ai
Production environment: true

Switch Active Profile

Change the active profile:

# Switch to staging
kdx config use-profile staging

# Verify the switch
kdx config current-profile

Delete a Profile

Remove a profile you no longer need:

kdx config delete-profile old-environment

There is no confirmation prompt when deleting profiles. Double-check the profile name before executing.

Production Environment Protection

KDX CLI provides safety mechanisms to prevent accidental changes to production environments.

Marking Profiles as Production

When creating or updating a profile, add the --production flag to enable safety prompts:

kdx config set-profile prod \
  --url https://platform.kodexa.ai \
  --api-key sk_production_key \
  --production

Production Confirmation Prompts

When using a profile marked as production, KDX CLI will prompt for confirmation before executing potentially destructive operations:

kdx create - Creating new resources
kdx apply - Applying resource configurations
kdx delete - Deleting resources
kdx sync push - Pushing metadata changes

Example:

kdx delete workspace old-workspace --profile prod

Prompt:

⚠️  This action may make changes.
Profile 'prod' is marked as a production environment.
Proceed with deleting workspace 'old-workspace'? [y/N]:

Type y or yes to proceed, or press Enter to cancel.

Skipping Production Confirmations

For automation and CI/CD pipelines, you can skip production confirmations:

# Skip confirmation for a single command
kdx delete workspace old-workspace --skip-production-confirm

# Works with any destructive operation
kdx apply -f resources.yaml --skip-production-confirm

When using --skip-production-confirm, the CLI logs a warning message indicating that production confirmation was bypassed. This helps with audit trails.

Best Practices

Do:

Mark all production profiles with --production flag
Review changes carefully before confirming
Use --skip-production-confirm only in trusted automation

Don’t:

Add --skip-production-confirm to shell aliases
Mark development environments as production
Bypass confirmations for manual operations

Command-Line Overrides

You can override profile settings on a per-command basis without modifying your configuration.

Override with a Different Profile

Use a specific profile for a single command:

# Use production profile for this command
kdx get workspaces --profile prod

# Use staging profile
kdx describe project demo --profile staging

Override with Direct Credentials

Bypass profiles entirely and provide credentials directly:

kdx get workspaces \
  --url https://custom.kodexa.ai \
  --api-key sk_custom_key

Direct credential overrides are useful for testing or one-off operations without creating a permanent profile.

Precedence Order

When multiple credential sources are available, KDX CLI follows this precedence:

Command-line flags (--url, --api-key)
Profile flag (--profile)
Current active profile (from currentProfile in config)
Environment variables (if implemented)

Security Best Practices

Protect Your Configuration File

The config.yaml file contains sensitive API keys. Protect it:

# Set restrictive permissions (Unix/Linux/macOS)
chmod 600 ~/.kodexa/config.yaml

# Verify permissions
ls -la ~/.kodexa/config.yaml

Expected output:

-rw------- 1 user user 512 Nov 7 10:30 /home/user/.kodexa/config.yaml

Never Commit Credentials

Add ~/.kodexa/ to your global Git ignore:

# Add to global gitignore
echo ".kodexa/" >> ~/.gitignore_global
git config --global core.excludesfile ~/.gitignore_global

Use Environment-Specific Keys

Create separate API keys for each environment with minimal necessary permissions:

Development keys - Limited to test data
Staging keys - Read/write access to staging resources
Production keys - Carefully scoped production access

Rotate Keys Regularly

Update API keys periodically:

# Generate new key in Kodexa platform
# Then update your profile
kdx config set-profile prod \
  --url https://platform.kodexa.ai \
  --api-key sk_new_rotated_key

Use Read-Only Keys for CI/CD

For automation and CI/CD pipelines, use API keys with read-only permissions when possible:

kdx config set-profile ci-readonly \
  --url https://platform.kodexa.ai \
  --api-key sk_readonly_ci_key

Cache Management

KDX CLI caches OpenAPI specifications to improve performance.

View Cache Location

ls -la ~/.kodexa/cache/

Refresh Cache

Force a cache refresh to get the latest resource definitions:

kdx api-resources --refresh

Clear Cache

Manually clear the cache if experiencing issues:

rm -rf ~/.kodexa/cache/
kdx api-resources --refresh

The cache is automatically created and updated as needed. Manual intervention is rarely required.

Cache Behavior

Initial request: KDX CLI fetches the OpenAPI spec and caches it
Subsequent requests: Uses cached spec for faster command execution
Stale detection: Automatically refreshes when the platform version changes
Manual refresh: Use --refresh flag to force update

Configuration Templates

Create a template file for team members (without API keys):

kodexa-profiles-template.yaml

currentProfile: local
profiles:
  local:
    url: http://localhost:8080
    apiKey: "YOUR_LOCAL_API_KEY"
  staging:
    url: https://staging.kodexa.ai
    apiKey: "YOUR_STAGING_API_KEY"
  prod:
    url: https://platform.kodexa.ai
    apiKey: "YOUR_PROD_API_KEY"
    productionEnvironment: true

Team members can copy this template and add their own keys:

# Copy template
cp kodexa-profiles-template.yaml ~/.kodexa/config.yaml

# Edit and add personal API keys
vim ~/.kodexa/config.yaml

Export Profile (Without Keys)

For documentation or sharing URLs:

kdx config list-profiles | grep -v "apiKey"

Advanced Configuration

Use in Scripts

Create automation scripts that switch profiles:

#!/bin/bash
# deploy-to-staging.sh

# Switch to staging profile
kdx config use-profile staging

# Apply configurations
kdx apply -f workspace.yaml
kdx apply -f project.yaml

# Verify deployment
kdx get workspaces

Profile-Based Deployment Pipeline

#!/bin/bash
# multi-env-deploy.sh

ENVIRONMENTS=("dev" "staging" "prod")

for ENV in "${ENVIRONMENTS[@]}"; do
  echo "Deploying to $ENV..."
  kdx config use-profile "$ENV"
  kdx apply -f "configs/$ENV/"
  
  if [ $? -eq 0 ]; then
    echo "✓ Deployment to $ENV successful"
  else
    echo "✗ Deployment to $ENV failed"
    exit 1
  fi
done

Parallel Operations Across Profiles

# Get workspaces from all environments
for profile in local staging prod; do
  echo "=== $profile ==="
  kdx get workspaces --profile "$profile" -o json | jq '.[].name'
done

Troubleshooting

”No active profile configured”

Create a profile first:

kdx config set-profile local --url http://localhost:8080 --api-key your-key

“Profile not found”

List available profiles to verify the name:

kdx config list-profiles

“Permission denied” on config file

Fix file permissions:

chmod 600 ~/.kodexa/config.yaml

Config file corrupted

Back up and recreate:

cp ~/.kodexa/config.yaml ~/.kodexa/config.yaml.backup
rm ~/.kodexa/config.yaml
kdx config set-profile local --url http://localhost:8080 --api-key your-key

KDX CLI

Kodexa CLI (Legacy)

​Migrating from Profiles to Environment Variables

​Key Differences

​Migration Steps

​Benefits of Environment Variables

​For CI/CD Pipelines

​Backwards Compatibility

​Understanding Profiles (Legacy Reference)

​Configuration File Location

​Configuration File Structure

​Creating Profiles

​Create a New Profile

​Create Multiple Profiles

​Update an Existing Profile

​Managing Profiles

​List All Profiles

​View Current Profile

​Switch Active Profile

​Delete a Profile

​Production Environment Protection

​Marking Profiles as Production

​Production Confirmation Prompts

​Skipping Production Confirmations

​Best Practices

​Command-Line Overrides

​Override with a Different Profile

​Override with Direct Credentials

​Precedence Order

​Security Best Practices

​Protect Your Configuration File

​Never Commit Credentials

​Use Environment-Specific Keys

​Rotate Keys Regularly

​Use Read-Only Keys for CI/CD

​Cache Management

​View Cache Location

​Refresh Cache

​Clear Cache

​Cache Behavior

​Configuration Templates

​Share Profile Templates

​Export Profile (Without Keys)

​Advanced Configuration

​Use in Scripts

​Profile-Based Deployment Pipeline

​Parallel Operations Across Profiles

​Troubleshooting

​”No active profile configured”

​“Profile not found”

​“Permission denied” on config file

​Config file corrupted

​Next Steps

Resource Operations

Metadata Sync

Migrating from Profiles to Environment Variables

Key Differences

Migration Steps

Benefits of Environment Variables

For CI/CD Pipelines

Backwards Compatibility

Understanding Profiles (Legacy Reference)

Configuration File Location

Configuration File Structure

Creating Profiles

Create a New Profile

Create Multiple Profiles

Update an Existing Profile

Managing Profiles

List All Profiles

View Current Profile

Switch Active Profile

Delete a Profile

Production Environment Protection

Marking Profiles as Production

Production Confirmation Prompts

Skipping Production Confirmations

Best Practices

Command-Line Overrides

Override with a Different Profile

Override with Direct Credentials

Precedence Order

Security Best Practices

Protect Your Configuration File

Never Commit Credentials

Use Environment-Specific Keys

Rotate Keys Regularly

Use Read-Only Keys for CI/CD

Cache Management

View Cache Location

Refresh Cache

Clear Cache

Cache Behavior

Configuration Templates

Share Profile Templates

Export Profile (Without Keys)

Advanced Configuration

Use in Scripts

Profile-Based Deployment Pipeline

Parallel Operations Across Profiles

Troubleshooting

”No active profile configured”

“Profile not found”

“Permission denied” on config file

Config file corrupted

Next Steps