Profile Command

Setup and initialization of the Keeper Secrets Manager device profile

profile command

Description: Initialize and switch between device profiles. In order to support multiple environments on the same device, you can also switch between Secrets Manager device profiles.

Parameters:

Sub-command and options to run

format: ksm profile <sub-command>

---

Storage Options

The KSM CLI v1.3.0+ supports two methods for securely storing profile configuration. Which method is used depends on how you installed the CLI:

Installation Method Determines Default Storage

With OS-Native Secure Storage (Recommended):

Install with keyring support:

pip3 install keeper-secrets-manager-cli[keyring]

Profiles are automatically stored in your operating system's native secure storage:

Operating System	Secure Storage Backend
macOS	Keychain
Windows	Windows Credential Manager
Linux	Secret Service (GNOME Keyring, KWallet)

Benefits:

• Configurations are encrypted at the OS level

• No plain-text configuration files

• Protected by your system login/biometrics

• Survives system updates and reinstalls

Without Keyring (File-Based Storage):

Install without keyring:

pip3 install keeper-secrets-manager-cli

Profiles are stored in a keeper.ini file. This method is suitable for:

• Containerized environments (Docker, Kubernetes)

• CI/CD pipelines

• Headless servers without a running Secret Service daemon (GNOME Keyring, KWallet)

---

Sub-Commands:

init

Initialize a client device profile.

ksm profile init

Storage Behavior

When you run profile init, the storage method depends on your installation:

• With keyring support: Profile stored in OS-native secure storage (macOS Keychain, Windows Credential Manager, or Linux Secret Service)

• Without keyring support: Profile stored in keeper.ini file with a warning message

• With --ini-file flag: Saves profile to this specific file using file-based storage (for Docker/CI-CD use)

Output Examples

With keyring support installed:

$ ksm profile init XX:XXXXXXXX

Output (macOS):

Added profile _default to macOS Keychain

Output (Windows):

Added profile _default to Windows Credential Manager

Output (Linux):

Added profile _default to system keyring

Without keyring support:

$ ksm profile init XX:XXXXXXXX

Output:

Warning: Keyring not available, using keeper.ini file instead
Warning: For better security, install: pip install keeper-secrets-manager-cli[keyring]
Set keeper.ini permissions to 0600 (owner-only access)
Added profile _default to INI config file located at /path/to/keeper.ini

Using a custom file path:

Use --ini-file to save the profile to a specific file location instead of the default keeper.ini. This uses file-based storage — useful for generating config files for Docker containers or CI/CD pipelines from a developer machine.

$ ksm profile init --ini-file keeper.ini --token XX:XXXXXXXX

Output (with keyring support installed — typical developer machine):

Added profile _default to macOS Keychain
Set keeper.ini permissions to 0600 (owner-only access)
Exported profile _default to INI file at keeper.ini (for Docker/CI-CD use)
  Active profile will continue to use macOS Keychain

Output (without keyring support):

Set keeper.ini permissions to 0600 (owner-only access)
Added profile _default to INI config file located at keeper.ini

INI File Locations

If using file-based storage, the keeper.ini file will be created in your current working directory. For the Windows or macOS binary applications, the keeper.ini will be created in the user's home directory ($HOME or %USERPROFILE% environment variables).

The CLI searches for keeper.ini in the following locations (in order):

Unix/Linux/macOS:

• Path defined by $KSM_INI_DIR environment variable

• Current working directory

• $HOME/keeper.ini

• $HOME/.config/ksm/keeper.ini

• $HOME/.keeper/keeper.ini

• /etc/keeper.ini

• /etc/ksm/keeper.ini

• /etc/keeper/keeper.ini

Windows:

• Path defined by %KSM_INI_DIR% environment variable

• Current working directory

• %USERPROFILE%\keeper.ini

• %ProgramData%\Keeper\keeper.ini

• %ProgramFiles%\Keeper\keeper.ini

Parameters:

• -t, --token <token> - One-time access token

• -h, --hostname <XX> - Destination region

  Defaults to US region. Customers hosted in other regions must set this value:

  • US (United States)

  • EU (Europe)

  • AU (Australia)

  • JP (Japan)

  • CA (Canada)

  • US_GOV (GovCloud)

• --ini-file <FILENAME> - Save profile to this file using file-based storage (for Docker/CI-CD use)

• -p, --profile-name <NAME> - Set profile name (defaults to "_default")

Usage Examples

Typically, you will be initializing the KSM CLI with a token created in the vault or in Keeper Commander:

ksm profile init --token XX:XXXXXXXX

To avoid exposing the token on the command line, use the KSM_CLI_TOKEN environment variable:

export KSM_CLI_TOKEN=XX:XXXXXXXX
ksm profile init --ini-file=/tmp/custom.ini --profile-name=non_default

Usage of KSM_CLI_TOKEN environment variable to provide one-time token allows for selecting a custom INI file and custom profile (to create/overwrite) and can be overridden by --token option from command line.

As described in the Quick Start Guide, you can create a token from the Commander CLI or from the Keeper Vault interface. For example:

My Vault> secrets-manager client add --app MyApplicationName

setup

Setup a new profile to be loaded from external storage like the AWS Secrets Manager. This is ideal when using Keeper Secrets Manager CLI from a cloud instance. Using this method of authentication adds additional layers of security.

Prerequisite: AWS integration requires the [aws] extra:

pip3 install keeper-secrets-manager-cli[aws]

Without it, profile setup --type=aws will fail with: Missing import dependencies: boto3

There are 3 ways of integrating with external storage providers like AWS:

• EC2 instance role (recommended)

• AWS profile credentials

• AWS custom keys

Method 1: EC2 instance role

For this method, you need to install Keeper Secrets Manager CLI on a EC2 instance which has been configured with a role that has permission to read specific AWS Secrets Manager secrets. We recommend setting up an EC2 role policy that has the least permission available, to only read specific keys. Learn more about AWS Secrets Manager access controls.

To initialize the KSM CLI profile on an EC2 instance using the AWS EC2 instance role:

ksm profile setup --type=aws

This creates a keeper.ini file which defines the secret key in AWS. For example:

# keeper.ini configuration

[_default]
storage = aws
provider = ec2instance
secret = ksm-config

By default, the secret key is assumed to be called ksm-config. You can specify a different key value by editing the keeper.ini file or using the --secret option. Example:

ksm profile setup --type=aws --secret my-ksm-config

Method 2: AWS profile credentials

The KSM CLI can be configured to use a specific AWS profile that has been previously initialized on this device with the aws configure command.

For this method, the AWS profile credentials should be assigned to a role which is limited to only read specific keys from the AWS Secrets Manager. Learn more about AWS Secrets Manager access controls.

For example:

ksm profile setup --type=aws --secret=ksm-config --credentials=profile --credentials-profile=default

Method 3: AWS custom keys

The KSM CLI can be configured to use a specific AWS Access Key / Secret Key pair. In this scenario, the Access Key and Secret Key will be stored locally in the keeper.ini file.

For example:

ksm profile setup --type=aws --secret=ksm-config --credentials=keys --aws-access-key-id XXX --aws-secret-access-key XXX --region XXX

An additional flag --fallback allows you to specify falling back to the default profile (from the AWS local configuration) if the initial credentials fail.

Finishing the KSM CLI setup

To complete the setup, a base64 KSM configuration value must be generated from the Keeper Vault interface or the Keeper Commander CLI. This is described in the Quick Start Guide.

For example, using the Commander CLI, this can be generated using a command such as the one below:

My Vault> secrets-manager client add --app "My KSM App" --config-init b64

Successfully generated Client Device
====================================

Initialized Config: [Base64 Config....]

Copy the provided configuration for use in the next step.

In order for this KSM device to authenticate against Keeper Secrets Manager, the KSM configuration value in base64 format must be populated into the AWS Secrets Manager. For example, using the AWS CLI:

aws secretsmanager create-secret --name ksm-config --secret-string '[Base64 Config]'

Now, you can verify that KSM CLI works and can access secrets from your vault using:

ksm secret list

 UID                     Record Type          Title
 ----------------------- -------------------- --------------------------
 n9SdOX1cEyMj9Ttj3lsjYQ  pamUser              IAM Account: demouser
 WfxgS6E_bY_tzdIChYIsAA  login                Amazon AWS - john
 toAfybW5SsbhRT9LtZ7oyg  serverCredentials    QA Server

Additional setup options

--ini-file <FILENAME> save the new profile to this file instead of keeper.ini. -p, --profile-name <NAME> set profile name. If not provided, the profile will be set as "default"

list

List all available profiles for the current Client Device.

ksm profile list

Example:

$ ksm profile list

  Active   Profile
 ======== ===============
           Production
  *        Test Server 1
           Test Server 2
           Local Dev

export

Export the current profile into a base64-encoded string.

ksm profile export [--plain] [--file-format] [PROFILE NAME]

optional parameters:

• --plain Export profile without base64-encoding the string.

• --file-format Export a profile to a specific file format. Available formats are:

  • ini - To be used by another instance of the CLI.

  • json - Can be used by the CLI and other Developer SDKs.

Example

$ ksm profile export my_profile

Note: When using an external storage provider for KSM configuration, the profile will not be exportable.

import

Import a client device profile from an encrypted base64-encoded string.

ksm profile import [--output-file "INI filename"] <BASE64 CONFIG>

optional parameters:

• --output-file <INI filename> Where to create the INI configuration file. If not set, will be create in current directory.

$ ksm profile import --output-file=my_profile BASE64_ENC_CONFIG

active

Set the currently active profile for this client device.

ksm profile active <PROFILE NAME>

Example:

$ ksm profile active production

production is now the active profile.

delete

Delete a profile from the local client device. Works with both keyring and file-based (INI) storage.

ksm profile delete <PROFILE NAME>

Parameters:

• PROFILE NAME (required) - The name of the profile to delete

Behavior:

• Keyring storage: Removes the profile from OS-native secure storage and updates the profile list

• File-based storage: Removes the profile from the keeper.ini file

• If the deleted profile was the active profile, the active profile is cleared

Example:

$ ksm profile delete production

Profile production has been deleted.

This action is immediate and cannot be undone. If you need the profile again, you will need to re-initialize it with a new one-time access token.

Profiles within Containers

If you are running the CLI inside of a containerized environment, you might not have the ability to initialize a profile. If no INI config file is found and the environment variable KSM_TOKEN is found, a default profile will be auto-generated. A INI config file will be created and stored in the current working directory. That can be overridden with the environment variable KSM_INI_DIR.

Default INI Filename

The default name of the ini file is keeper.ini, however this can overridden by using the KSM_INI_FILE environment variable. By using KSM_INI_DIR and KSM_INI_FILE environment variables you can completely change the location and name of the INI configuration file.

---

Troubleshooting

Clearing Keyring Credentials

To completely remove KSM CLI credentials from your OS secure storage:

macOS:

Using Keychain Access app:

1. Open Keychain Access application

2. Search for "KSM-cli"

3. Delete all matching entries (ksm-cli-common, ksm-cli-profile-*)

Using command line:

# Delete common config and its integrity hash
security delete-generic-password -s "KSM-cli" -a "ksm-cli-common"
security delete-generic-password -s "KSM-cli" -a "ksm-cli-common-integrity"

# Delete default profile and its integrity hash
security delete-generic-password -s "KSM-cli" -a "ksm-cli-profile-_default"
security delete-generic-password -s "KSM-cli" -a "ksm-cli-profile-_default-integrity"

# For other profiles, replace "_default" with your profile name
# (remember to also delete the corresponding -integrity entry)

Windows:

Using Credential Manager:

1. Open Control Panel > Credential Manager

2. Click Windows Credentials

3. Search for "KSM-cli"

4. Expand each entry and click Remove

Using command line (PowerShell):

# Delete common config and its integrity hash
cmdkey /delete:"KSM-cli:ksm-cli-common"
cmdkey /delete:"KSM-cli:ksm-cli-common-integrity"

# Delete default profile and its integrity hash
cmdkey /delete:"KSM-cli:ksm-cli-profile-_default"
cmdkey /delete:"KSM-cli:ksm-cli-profile-_default-integrity"

# For other profiles, replace "_default" with your profile name
# (remember to also delete the corresponding -integrity entry)

Linux:

Using Seahorse (GUI):

1. Open Passwords and Keys application (Seahorse)

2. Navigate to Login keyring

3. Search for "KSM-cli"

4. Right-click and delete all matching entries

Using command line (requires secret-tool):

# Delete common config and its integrity hash
secret-tool clear service KSM-cli username ksm-cli-common
secret-tool clear service KSM-cli username ksm-cli-common-integrity

# Delete default profile and its integrity hash
secret-tool clear service KSM-cli username ksm-cli-profile-_default
secret-tool clear service KSM-cli username ksm-cli-profile-_default-integrity

# For other profiles, replace "_default" with your profile name
# (remember to also delete the corresponding -integrity entry)

Keyring Not Available Error

If you see this warning when running ksm profile init:

Warning: Keyring not available, using keeper.ini file instead
Warning: For better security, install: pip install keeper-secrets-manager-cli[keyring]

Causes:

• KSM CLI was installed without the [keyring] extra

• The Python keyring library is not available

• On Linux: No supported keyring backend (GNOME Keyring, KWallet)

Solutions:

Option 1 - Enable keyring support (recommended):

pip3 install --upgrade keeper-secrets-manager-cli[keyring]

Then re-run ksm profile init to store the profile in your OS keyring.

Option 2 - Continue using file-based storage:

No action needed. The CLI will continue using keeper.ini file storage, which works in all environments including containers and CI/CD pipelines.

Checking Your Current Storage Method

To see which storage method is currently in use:

# If using keyring, profiles won't be in keeper.ini
ls -la keeper.ini  # File won't exist or will be empty

# On macOS, check Keychain (lists all KSM-cli entries)
security find-generic-password -s "KSM-cli" 2>/dev/null \
  && echo "Keyring storage is active" \
  || echo "No keyring entries found"

# On Windows, check Credential Manager
cmdkey /list | findstr "KSM-cli"

# On Linux, check with secret-tool
secret-tool search service KSM-cli

Migrating Between Storage Methods

From INI file to Keyring:

1. Install keyring support: pip3 install keeper-secrets-manager-cli[keyring]

2. Generate a new one-time token from Keeper Vault or Commander CLI

3. Delete the old INI file: rm keeper.ini

4. Re-initialize: ksm profile init --token <NEW_TOKEN>

   • With keyring installed, the profile is stored in OS-native secure storage automatically

Note: A new one-time token is required because tokens are consumed on first use.

From Keyring to INI file:

1. Export existing profile: ksm profile export _default

   1. Copy the base64 output, then paste it as <BASE64_CONFIG> in step 2

2. Import with file flag: ksm profile import --output-file keeper.ini <BASE64_CONFIG>

3. Clear keyring (optional): Follow "Clearing Keyring Credentials" above