The Kodexa CLI uses profiles to manage connections to different Kodexa platform instances. This page explains how to authenticate with the platform and manage your profiles.

​
Logging In

To authenticate with a Kodexa platform instance, use the login command:

kodexa login

You’ll be prompted to enter:

  • The URL of the Kodexa platform instance
  • Your access token for authentication
  • A profile name (defaults to “default”)

You can also provide these directly in the command:

kodexa login --url https://your-platform-url --token your-access-token

​
Profile Management

Profiles allow you to manage connections to multiple Kodexa platform instances. Each profile stores a URL and access token for a specific instance.

​
Creating Profiles

When you log in, you automatically create a profile. You can specify a profile name during login:

kodexa login --profile dev-environment

If you don’t specify a profile name, it defaults to “default”.

You can create multiple profiles for different environments:

# Create a development profile
kodexa login --url https://dev.kodexa.com --token your-dev-token --profile dev

# Create a production profile
kodexa login --url https://prod.kodexa.com --token your-prod-token --profile prod

​
Viewing Profiles

To list all available profiles:

kodexa profiles

This shows all configured profiles and their associated URLs:

Available profiles:
* default (https://kodexa.com)
  dev (https://dev.kodexa.com)
  prod (https://prod.kodexa.com)

The profile with an asterisk (*) is the currently active profile.

​
Checking Current Profile

To check which profile is currently active:

kodexa profile

This displays information about the current profile:

Current profile: default
URL: https://kodexa.com

​
Switching Profiles

To switch to a different profile:

kodexa profile prod

Replace prod with the name of the profile you want to use.

After switching, you can verify the change:

kodexa profile

​
Deleting Profiles

To delete a profile when you no longer need it:

kodexa profile dev --delete

You’ll be prompted to confirm the deletion:

Are you sure you want to delete the profile 'dev'? [y/N]: y
Profile 'dev' deleted.

​
Profile Configuration File

Profiles are stored in a configuration file on your system. The location depends on your operating system:

  • macOS: ~/Library/Application Support/kodexa-cli/profiles.json
  • Linux: ~/.local/share/kodexa-cli/profiles.json
  • Windows: C:\Documents and Settings\{User}\Application Data\Local Settings\kodexa\kodexa-cli\profiles.json

​
Platform Information

To verify your connection and view information about the platform you’re connected to:

kodexa platform

This displays details about the Kodexa platform instance you’re currently connected to.

To see detailed information, add the verbose flag:

kodexa platform -v

​
Token Storage

Your authentication tokens are securely stored in your system:

  • macOS: ~/Library/Application Support/kodexa-cli
  • Linux: ~/.local/share/kodexa-cli
  • Windows: C:\Documents and Settings\{User}\Application Data\Local Settings\kodexa\kodexa-cli or C:\Documents and Settings\{User}\Application Data\kodexa\kodexa-cli

​
Environment Variable Authentication

You can also authenticate using environment variables:

export KODEXA_ACCESS_TOKEN=your-access-token
export KODEXA_URL=https://your-platform-url

When set, these environment variables take precedence over profile settings.

​
Global Options

Most Kodexa CLI commands accept the following authentication-related options:

--url URL      # The URL to the Kodexa server
--token TOKEN  # Access token
--profile NAME # The profile to use for this command

These options override the active profile settings for individual commands.

​
Best Practices

  1. Use different profiles for different environments (development, production, etc.)
  2. Avoid storing tokens in scripts or sharing them with others
  3. Regularly rotate your access tokens for security
  4. Use the --profile option for one-off commands instead of switching profiles