> For the complete documentation index, see [llms.txt](https://docs.keeper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeper.io/keeperpam/secrets-manager/secrets-manager-command-line-interface/profile-command.md).

# Profile Command

**Description:** Initialize and manage device profiles. Use profiles to support multiple Keeper Secrets Manager environments on the same device.

**Parameters:**

Sub-command and options to run

format: **`ksm profile <sub-command>`**

**Sub-Commands:**

| Sub-Command | Description                                                                   |
| ----------- | ----------------------------------------------------------------------------- |
| `init`      | Initialize a new client device profile                                        |
| `setup`     | Set up a new profile from a third-party external secrets manager such as AWS. |
| `list`      | List all profiles and identify the active profile.                            |
| `export`    | Export a configuration profile                                                |
| `import`    | Create a new configuration from an exported encrypted profile                 |
| `active`    | Set the active configuration profile.                                         |
| `delete`    | Delete a profile                                                              |

## **init**

Initialize a client device profile.

```
ksm profile init
```

When the CLI is installed with the `keyring` extra, `ksm profile init` stores the new profile in the operating system's native secure storage (macOS Keychain, Windows Credential Manager, or Linux Secret Service). The CLI does not create a `keeper.ini` file.

To store the profile in a `keeper.ini` file instead, pass the `--ini-file <FILENAME>` option. If the `keyring` extra is not installed, the CLI prints a warning and falls back to a `keeper.ini` file, created in your current working directory (or in your home directory for the Windows and macOS binary applications).

{% hint style="warning" %}
**Locked keyring (SSH and headless sessions):** If the `keyring` extra is installed but the OS keyring is locked and cannot be unlocked without an interactive session (for example, when connecting over SSH without a display server available, such as a locked GNOME Keyring), the CLI exits with an error instead of silently returning no profiles. Pass `--ini-file <PATH>` to read from a `keeper.ini` file, or set the `KSM_CONFIG` environment variable to a base64-encoded configuration string.
{% endhint %}

When a `keeper.ini` file is used, the CLI searches these locations in order and uses the first one it finds:

* The current directory
* The path defined by the environmental variable **`KSM_INI_DIR`**
* The user's home directory
  * `${HOME}`
  * `${HOME}/.config/ksm`
  * `${HOME}/.keeper`
  * `$env:USERPROFILE`
* Various system directories
  * `/etc`
  * `/etc/ksm`
  * `/etc/keeper`
  * `$env:APPDATA/Keeper`
  * `$env:ProgramData/Keeper`
  * `$env:ProgramFiles/Keeper`

{% hint style="warning" %}
**A `keeper.ini` in the current directory takes precedence over `KSM_INI_DIR`.** If a `keeper.ini` file exists in the current directory, the CLI uses it even when `KSM_INI_DIR` points elsewhere, and prints a warning naming both paths. Pass `--ini-file` with the full path to force the intended file, or set `KSM_INI_DIR_SKIP_CONFLICT_WARNING=TRUE` to silence the warning without changing this behavior.
{% endhint %}

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 the new profile to this file
* `-p, --profile-name <NAME>` set profile name\
  If not provided, the profile will be set as "\_default"

Typically, you will initialize the KSM CLI with a token created in the Keeper Vault or in Keeper Commander. For example:

```
ksm profile init --token XX:XXXXXXXX
```

To prevent the token from appearing on the command line, use the `KSM_CLI_TOKEN` environment variable. For example:

```
ksm profile init --ini-file=/tmp/custom.ini --profile-name=non_default
```

{% hint style="warning" %}
The `KSM_CLI_TOKEN` environment variable lets you select a custom INI file and profile name *(to create/overwrite)*. The `--token` option overrides it.
{% endhint %}

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

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

## **setup**

Set up a new profile that loads from external storage such as AWS Secrets Manager. This is ideal when you run the Keeper Secrets Manager CLI from a cloud instance. This authentication method adds extra security.

You can integrate with external storage providers such as AWS in three ways:

* EC2 instance role (recommended)
* AWS profile credentials
* AWS custom keys

### Method 1: EC2 instance role

{% hint style="info" %}
For this method, install Keeper Secrets Manager CLI on an EC2 instance that is configured with a role that has permission to read specific AWS Secrets Manager secrets. Create an EC2 role policy with the least permission needed to read only specific keys. [Learn more](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html) about AWS Secrets Manager access controls.
{% endhint %}

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 that defines the secret key in AWS. For example:

```
....

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

The CLI assumes the secret key is named `ksm-config` by default. To use a different key, edit the `keeper.ini` file or use the `--secret` option. For 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](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html#getting-started-quickstart-new).

{% hint style="info" %}
For this method, assign the AWS profile credentials to a role that can only read specific keys from AWS Secrets Manager. [Learn more](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html) about AWS Secrets Manager access controls.
{% endhint %}

For example:

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

### Method 3: AWS custom keys

The KSM CLI can use a specific AWS Access Key / Secret Key pair. The CLI stores the Access Key and Secret Key locally in the `keeper.ini` file.

For example:

{% code overflow="wrap" %}

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

{% endcode %}

The `--fallback` flag lets you fall back to the default profile (from the AWS local configuration) if the initial credentials fail.

### Finishing the KSM CLI setup

To complete the setup, generate a base64 KSM configuration value from the Keeper Vault interface or the Keeper Commander CLI, as described in the Quick Start Guide.

For example, use the following Commander CLI command:

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

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

Initialized Config: [Base64 Config....]
```

Copy the configuration for the next step.

To allow this KSM device to authenticate against Keeper Secrets Manager, upload the base64 configuration value to AWS Secrets Manager. For example, using the AWS CLI:

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

Verify that the KSM CLI can access secrets from your vault:

```
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 as a base64-encoded string.

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

Optional parameters:

* `--plain` Export the profile without base64-encoding.
* `--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
```

If the KSM configuration uses an external storage provider, the profile cannot be exported.

## 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>` Path to the INI configuration file. If not set, the CLI creates the file in the 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 current Client Device. The CLI removes the profile from whichever storage holds it (OS keyring or `keeper.ini`). If the deleted profile was the active profile, the CLI clears the active-profile pointer.

`ksm profile delete <PROFILE NAME>`

Example:

```
$ ksm profile delete "Test Server 1"

Profile Test Server 1 has been deleted.
```

## **Profiles within Containers**

If you run the CLI in a container, you may not be able to initialize a profile. If the CLI finds no INI config file and **`KSM_TOKEN`** is set, it generates a default profile. The CLI creates the INI config file in the current working directory. Set **`KSM_INI_DIR`** to use a different directory.

## **Default INI Filename**

The default INI filename is `keeper.ini`. Set **`KSM_INI_FILE`** to use a different name. Use **`KSM_INI_DIR`** and **`KSM_INI_FILE`** together to set a custom directory and filename for the INI configuration file.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.keeper.io/keeperpam/secrets-manager/secrets-manager-command-line-interface/profile-command.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.