Profiles & Configuration - Kodexa Developer Portal

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

Understanding Profiles

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

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

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

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

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                          CURRENT
local      http://localhost:8080        
staging    https://staging.kodexa.ai    
prod       https://platform.kodexa.ai   ✓

View Current Profile

Check which profile is currently active:

kdx config current-profile

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.

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"

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

Kodexa CLI

KDX CLI (Coming 2026)

​Understanding Profiles

​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

​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

Understanding Profiles

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

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