# Secret Command

## `secret` command

**Description:** Retrieve secrets from the vault and parse the response.

**Parameters:**

Sub-command to run

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

**Sub-Commands:**

| Sub-Command         | Description                                                   |
| ------------------- | ------------------------------------------------------------- |
| `list`              | List all secrets associated with the application              |
| `get`               | Get a secret from the vault, or specific fields from a secret |
| `add`               | Add a new secret to the vault.                                |
| `update`            | Update a field within an existing secret                      |
| `delete`            | Delete secrets from the vault.                                |
| `upload`            | Upload a file attachment to an existing secret                |
| `download`          | Download a vault secret file attachment by name               |
| `delete-attachment` | Delete one or more file attachments by name or UID            |
| `template`          | Display a record type template                                |
| `notation`          | Test templating environment variables for the `exec` command  |
| `totp`              | Generate pass code from a TOTP field of the secret            |
| `password`          | Generate a password                                           |

### **list**

List all secrets associated with the application

`ksm secret list`

optional parameters:

* `--json` return in JSON format
* `--uid <RECORD UID(s)>` get specific records by Record UID
* `-t, --title <REGEX>` get records with title matching the REGEX
* `-f, --folder <folder UID>` List only records in the selected folder UID.
* `-r, --recursive` list recursively all records in the selected folder UID including all subfolders.
* `-q, --query <JSONPath Query>` List only records matching the JSON Path query.
* `-v, --show-value` print matching value instead of the record title when using JSON Path query.

{% hint style="info" %}
The **--query** switch uses JSONPath, a query syntax based on XPath\
[**https://tools.ietf.org/id/draft-goessner-dispatch-jsonpath-00.html**](https://tools.ietf.org/id/draft-goessner-dispatch-jsonpath-00.html)
{% endhint %}

**Example 1:** Tabular format

```
$ ksm secret list

 UID                     Record Type          Title                    
 ----------------------- -------------------- -------------------------
 SNzjw8tM1HsXEzXERCJrNQ  login                Stripe API Key           
 8f8I-OqPV58o2r91wVgZ_A  databaseCredentials  Production MySQL Database
 hDFhwSUe6pTWdkJDSRmtBg  login                Amazon AWS              
```

**Example 2:** JSON format

```
$ ksm secret list --json
[
    {
        "uid": "SNzjw8tM1HsXEzXERCJrNQ",
        "title": "Stripe API Key",
        "record_type": "login"
    },
    {
        "uid": "8f8I-OqPV58o2r91wVgZ_A",
        "title": "Production MySQL Database",
        "record_type": "databaseCredentials"
    },
    {
        "uid": "hDFhwSUe6pTWdkJDSRmtBg",
        "title": "Amazon AWS",
        "record_type": "login"
    }
]
```

**Example 3:** Search by Title while filtering by folder

```
$ ksm secret list --recursive --folder=KOx3pRkAnODGVWyDuK7ttw -t Stripe

 UID                     Record Type          Title         
 ----------------------- -------------------- --------------
 SNzjw8tM1HsXEzXERCJrNQ  login                Stripe API Key
```

**Example 4:** Search by field attributes using JSONPath

```
$ ksm secret list --query=$.custom[?(@.type==text)].value

 UID                     Record Type          Title
 ----------------------- -------------------- --------------
 SNzjw8tM1HsXEzXERCJrNQ  login                Stripe API Key

$ ksm secret list -v --query=$.custom[?(@.type==text)].value

 UID                     Record Type          Value
 ----------------------- -------------------- ---------------
 SNzjw8tM1HsXEzXERCJrNQ  login                <API_Key_Value>
```

**Example 5:** Search by custom field label and value using JSONPath

```
$ ksm secret list -v -q '$.custom[?(@.label=="app" & @.value[0]=="staging")]'

 UID                Record Type Value
 ------------------ ----------- --------------
 i0U9lwTwl-7pChw8Q  login       {'label': 'app', 'type': 'text', 'value': ['staging']}
 8r9hxdlL7MINO6cJ9  login       {'label': 'app', 'type': 'text', 'value': ['staging']}
```

### **get**

Get a secret from the vault, or specific fields from a secret

`ksm secret get <RECORD UID>`

requires at least one of the following parameter:

* `<RECORD UID>` - if retrieving one record, the record UID can be part of the command line argument.
* `-u, --uid <RECORD UID>` get a specific record by it's unique ID. Muliple -u can be used to get more than one record.
* `-t, --title <RECORD TITLE>` get a specific record by it's title.

optional parameters:

* `-f, --field <Field Type or Custom Field Label>` return the value of a specific field by label or type.
* `-q, --query <JSONPath Query>` list only records matching the JSON Path query.
* `--json` return in JSON format (required when --query used)
* `--raw` remove quotation marks from result
* `--force-array` return results as an array even if there is only one result
* `--unmask` show password values in table views
* `--inflate/--deflate` by default, references to other records will be loaded into a record. If --deflate is used, the reference records will not be loaded into the record.

{% hint style="info" %}
If your Record UID start with a dash ("-"), add "--" before to get the record\
\
`ksm secret get -- <RECORD UID>`
{% endhint %}

{% hint style="info" %}
The **--query** switch uses JSONPath, a query syntax based on XPath\
[**https://tools.ietf.org/id/draft-goessner-dispatch-jsonpath-00.html**](https://tools.ietf.org/id/draft-goessner-dispatch-jsonpath-00.html)
{% endhint %}

**Example 1:** Returning a Secret to the console with tabular format

```
$ ksm secret get 8f8I-OqPV58o2r91wVgZ_A

 Record: 8f8I-OqPV58o2r91wVgZ_A
 Title: Production MySQL Database
 Record Type: databaseCredentials

 Field     Value                                         
 --------- ----------------------------------------------
 text      MySQL                                         
 host      [{"hostName": "192.168.1.24", "port": "3306"}]
 login     user                                          
 password  ****                                

```

**Example 2:** Returning a Secret to the console with tabular format and password unmasked

```
 $ ksm secret get --unmask --uid 8f8I-OqPV58o2r91wVgZ_A
 
 Record: 8f8I-OqPV58o2r91wVgZ_A
 Title: Production MySQL Database
 Record Type: databaseCredentials

 Field     Value                                         
 --------- ----------------------------------------------
 text      MySQL                                         
 host      [{"hostName": "192.168.1.24", "port": "3306"}]
 login     user                                          
 password  ksv#$0sbnb7W@b3VGCHb           

```

**Example 3**: Retrieving the password field from a secret. There are 2 different methods of doing this.

```
# Using field searching
$ ksm secret get -u SNzjw8tM1HsXEzXERCJrNQ -f password

# Using query syntax
$ ksm secret get -u 8f8I-OqPV58o2r91wVgZ_A \
  --json --query '$.fields[?(@.type=="password")].value'

# Using query syntax for complex values
$ ksm secret get -u SNzjw8tM1HsXEzXERCJrNQ \
  --json --query '$.fields[?(@.type=="keyPair")].value[0].publicKey'
   
```

**Example 4**: Retrieving a particular Custom Field value. There are 2 different methods of doing this.

```
# Using field searching
$ ksm secret get -u SNzjw8tM1HsXEzXERCJrNQ -f "API Key"

# Using query notation
$ ksm secret get --uid SNzjw8tM1HsXEzXERCJrNQ \
  --json --query '$.custom[?(@.label=="API Key")].value'
```

{% hint style="info" %}
The query syntax is very flexible and can be used to search the JSON object for any type of desired response. Note that when typing custom field values in your request, make sure to escape '\\' and '=' characters with a '\\' character.
{% endhint %}

**Example 5:** Retrieving raw JSON for the individual secret

```
$ ksm secret get --unmask --uid 8f8I-OqPV58o2r91wVgZ_A --json
{
    "uid": "8f8I-OqPV58o2r91wVgZ_A",
    "title": "Production MySQL Database",
    "type": "databaseCredentials",
    "notes": "",
    "fields": [
        {
            "type": "text",
            "value": [
                "MySQL"
            ]
        },
        {
            "type": "host",
            "value": [
                {
                    "hostName": "192.168.1.24",
                    "port": "3306"
                }
            ]
        },
        {
            "type": "login",
            "value": [
                "user"
            ]
        },
        {
            "type": "password",
            "value": [
                "ksv#$0sbnb7W@b3VGCHb"
            ]
        },
        {
            "type": "fileRef",
            "value": []
        }
    ],
    "custom": [],
    "files": []
}
```

### add

Add a record to the vault. There is four ways to add a secret record: clone existing record, use visual editor, from a file, and from field arguments.

{% hint style="info" %}
The output of a successful record addition is the record UID(s) via standard out. There may be additional text, which is in standard error.
{% endhint %}

#### Editor

The editor command will launch an editor application with a record with placeholder values. Replace the placeholder values or remove the value all together. The editor application can be set via [`ksm config editor`](https://docs.keeper.io/en/keeperpam/secrets-manager/secrets-manager-command-line-interface/config-command) or it will use the editor specified by the **EDITOR** environment variable. If the editor is not set, the CLI will attempt to find an installed editor.

An editor with a UI can be set. For Windows and MacOS blocking may need to be enabled if the the editor instantly warns about placeholder still existing in the record template. This is because, without blocking, the CLI will attempt to process the record before you are finished editing.

{% hint style="warning" %}
On MacOS, blocking will wait until the application fully exits before processing the record data. This mean the application is closed and no longer in the dock, not that the editor window is closed.
{% endhint %}

{% hint style="warning" %}
On Windows, blocking will wait until the process is no longer in the task list. If the application is launched via a .bat or .cmd file, the process name will be different from the application that was launch. To properly handle this use [`ksm config editor`](https://docs.keeper.io/en/keeperpam/secrets-manager/secrets-manager-command-line-interface/config-command) to set up the editor.
{% endhint %}

{% hint style="info" %}
If the editor doesn't block, and a message about template markers is shown, the file can be rechecked by entering **r**. This can be done when the edit of the record has been finished and saved.
{% endhint %}

`ksm secret add editor --sf <STORAGE FOLDER UID> --rt <RECORD TYPE> [--title "TITLE"] [--notes "NOTES"] [-p] [-o yaml | json]`

Required parameters:

`--storage-folder-uid, --sf` The storage folder UID where the new secret record will be created.

`--record-type, --rt` The record type of the secret record.

Optional parameters:

`--title, -t` Title of the secret record.

`--notes, -n` Notes associated with the secret record.

`--password-generate, -p` Generate a password for any password field that does not have a value.

`--output-format, -o` The output format of the template in the editor. Can either be JSON or YAML. The default is JSON.

`--editor, -e` Override the editor. If using this parameter, the editor should cause blocking.

**Example:**

Launch an editor with a login record with placeholder values. Either set the value or replace the value altogther, save file and exist browser.

```
ksm secret add editor --sf XXXXXX --rt login -o yaml
<in the editor>
version: v3
kind: KeeperRecord
data:
- recordType: login
  title: '<#ADD: The title of record here. This is required.>'
  notes: '<#ADD: Add some notes or remove.>'
...
<save and exit from editor>
The following is the new record UID ...
["Ai9iFYWf6EOE0T9fV-ynBg"]
```

{% hint style="info" %}
You can remove the entire "value" key/value line if there is no value. You do not need to remove the field.
{% endhint %}

#### File

The file command is similar to editor command except done in two steps. The first step is getting a placeholder record file using the command ksm secret template. Then replacing the placeholder values and using this command to read in that file to create the record(s).

Using this command allows you create multiple records at one time.

`ksm secret add file --sf <STORAGE FOLDER UID> -f <TEMPLATE FILE> [-p]`

Required parameters:

`--storage-folder-uid, --sf` The storage folder UID where the new secret record will be created.

`--file, -f` Path and name of the record template file.

Optional parameters:

`--password-generate, -p` Generate a password for any password field that does not have a value.

**Example:**

Save a bank account record type with placeholder values. Edit in your favorite editor and save. Then add using the `ksm secret add file` command. Also generate a password in any blank password fields.

```
ksm secret template bankAccount -f new_bank_account_record.json
<edit new_bank_account_record.json in favortite editor>
ksm secret add file --sf XXXX -f new_bank_account_record.json -p
```

#### Field

The field command set the values of a record via key/value arguments passed into the command.

`ksm secret add field <--sf STORAGE FOLDER UID> <--rt RECORD TYPE> <--title "TITLE>"> [--notes "<NOTES>"] [-p] <"FIELDS" ...>`

Required parameters:

`--storage-folder-uid, --sf` The storage folder UID where the new secret record will be created.

`--record-type, --rt` The record type of the secret record.

`--title, -t` Title of the secret record.

`FIELDS` - Key/Value pairs of the fields and their values. There can be multiple fields.

Optional parameters:

`--notes, -n` Notes associated with the secret record.

`--password-generate, -p` Generate a password for any password field that does not have a value.

**Example:**

```
ksm secret add field --sf XXXX --rt bankAccount \
    -t "My Bank Account" -n "My Checking Account" -p \
    "f.bankAccount.accountType=Checking" \
    "f.bankAccount.routingNumber=ROUT123" \
    "f.bankAccount.accountNumber=ACC456" \
    'f.name={"first": "John", "last": "Smith"}' \
    "login=jsmith" \
    "url=http://mybank.com" \
    "c.text[Bank Hours]=7:00AM to 5:00PM" \
    'c.phone=[{"number": "5551234567", "type": "Home"}, {"number": "5550987654"}]'
    
The following is the new record UID ...
Ai9iFYWf6EOE0T9fV-ynBg
```

The structure of the `field` is \[`field section .`]<`field type`>\[`[field label]`]\[`. value key`]<`=value`>

The `field section` is where the field is to be set. '**f**' is the standard fields, '**c**' is the custom fields. If not included, the field default to the standard fields.

The `field type` is required. For the standard field section, the field type must be part of the record type schema. If you attempt to add a field that doesn't exist, an error with be displayed. For the custom field section, any field type can be added. They will be ordered as they are added.

The `field label` is optional. The field label is surrounded by `[]` directly after the `field type`. For the custom field section, if the label is not set, the record field type is used in the UI.

The `value key` is optional for field types that have complex value, such a `phone`, `bankAccount`, and `name`. The `value key` allows a value to be built in pieces instead of setting the value as a JSON value.

The `value` begins after the = character. If the value is complex, then JSON is set as the value. If using JSON make sure the quote the field appropriately. If the JSON uses double quotes, then surround the field with single quotes. And if you need both, then you will need to escape the quotes with a backslash (\\).

**Rules**

For standard fields, the order in which the fields are set does not matter. The fields will be ordered by the record type schema. Fields that do not exists in the record type schema standard fields cannot be added to the standard fields.

For custom field, the fields will be ordered the same as the order of the field arguments.

If you have multiple fields of the same type you will need to include a `field label` to make them unique.

*Value Key*

Setting values using value key is useful when setting one field, however there are rules when setting another field of the same type or when the field accepts multiple values (ie phone).

If you are setting more than one field of the same type, the use a `field label` will make the field unique.

```
ksm secret add field --sf XXXX --rt "Custom Record" \
    "name[My Doctor].first=Jane" \
    "name[My Doctor].last=Smith" \
    "name[My Lawyer].first=John" \
    "name[My Lawyer].last=Doe"
```

If a `field label` is not used, the prior values will overwrite the existing values.

*JSON Values*

A value can be set to a JSON value. For fields that allow multiple values, setting a JSON value will be consider a complete value. That means if a `value key` comes after a JSON value, an additional value will be added to the field. The example below will create a phone field with two values.

```
ksm secret add field --sf XXXX --rt "Custom Record" \
    'c.phone={"number": "5551234567"}' \
    "c.phone.number=5551111111"
```

If the JSON value is an array of JSON objects. the field is considered a completed field. This mean no additional values can be added the field. The following will result in an error about the fields last field not being unique. To make the field unique a `field label` can be added.

```
ksm secret add field --sf XXXX --rt "Custom Record" \
    'c.phone=[{"number": "5551234567"}, {"number": "55599999999"}]',
    "c.phone.number=5551111111"
ksm had a problem: Cannot add this field due to it not being unique. To make unique add a label to the field or make sure the label is not being duplicated.
```

### **delete**

Delete secrets associated with the application

`ksm secret delete`

* `--uid <RECORD UID(s)>` delete records by Record UID

optional parameters:

* `--json` return in JSON format

**Example 1:** Tabular format

```
$ ksm secret delete -u AAAAAAAAAAAAAAAAAAAAAA -u SNzjw8tM1HsXEzXERCJrNQ

 UID                     Response Code        Error                    
 ----------------------- -------------------- ---------
 AAAAAAAAAAAAAAAAAAAAAA  n/a                  Not Found
 SNzjw8tM1HsXEzXERCJrNQ  ok                  
```

**Example 2:** JSON format

```
$ ksm secret delete --json -u AAAAAAAAAAAAAAAAAAAAAA -u riEeV5KUeiGqXXSidg47Zw
[
    {
        "uid": "AAAAAAAAAAAAAAAAAAAAAA",
        "responseCode": "n/a",
        "error": "Not found"
    },
    {
        "uid": "riEeV5KUeiGqXXSidg47Zw",
        "responseCode": "ok",
        "error": null
    }
]
```

### **clone**

The `clone` command creates new record using data from an existing record with an option to set a new title.

`ksm secret add clone --uid <RECORD UID> --title "TITLE"`

Required parameters:

`--uid, -u` The record UID of existing record.

Optional parameters:

`--title, -t` Title of the new record.

**Example:**

```
ksm secret add clone --uid XXXX --title NewTitle
    
The following is the new record UID ...
Ai9iFYWf6EOE0T9fV-ynBg
```

### **update**

Update an existing field within an existing secret.

{% hint style="info" %}
Some field types are complex. This means the value contains arrays and/or dictionaries for the value. If you are using a field type that is complex, you will need to use the `--field-json` and `--custom-field-json` to set the values. The JSON structures can be found [here](https://docs.keeper.io/en/keeperpam/commander-cli/command-reference/record-commands/record-type-commands).
{% endhint %}

`ksm secret update --uid <RECORD UID>`

Optional Parameters:

* `--field` - Update the value of a specific standard field in the secret.
* `--custom-field` - Update the value of a specific custom field in the secret.
* `--field-json` - Update the value of a specific standard field using JSON. Use for complex field values.
* `--custom-field-json` - Update the value of a specific custom field using JSON. Use for complex field values.
* `--title, -t` - Update the title of the secret.
* `--notes, -n` - Update the notes of the secret.

The update will match your key on existing field and custom field labels. Anything that appears after the '=' character is assumed to be the value. No escaping values is required, unless you are wrapping the parameter value is quotes.

**Example 1:** Basic use case

```
# Update the password for a secret
$ ksm secret update --uid XXXXX --field password=xxxxxxxxxxx

# Update a custom field value
$ ksm secret update --uid XXXXX --custom-field "My Custom Label=XXXXX"
```

**Example 2:** If a key or field values contains a space, the entire parameter value needs to be wrapped in quotes. If your value contains quotes you need differnet quotes around the parameter value. For example, if your value contains JSON, use single quotes around the parameter value.

```
$ ksm secret update --uid XXXXX --custom-field "My Base64=SElUSEVSRQo="

$ ksm secret update --uid XXXXX --field-json 'name={"first": "John", "middle": "X", "last": "Doe"}'
```

### **upload**

Upload attachment to an existing secret in the vault

`ksm secret upload -u <RECORD UID> --file "<FILENAME>" --title "<FILE_TITLE>"`

Parameters:

* `-u, --uid <RECORD UID>` UID of the secret to upload to (Required)
* `-f, --file <FILENAME>` file path to the file to upload (Required)
* `-t, --title` file title - if not provided defaults to the file name (without the path) (Optional)

**Example:**

```
$ ksm secret upload -u oxhtLx9qrQIzeSXBtvQj2Q \
   --file "/path/to/SSHKey.pem" --title "SSHKey.pem"
```

### **download**

Download attachments from secrets in the vault, such as SSH keys

`ksm secret download -u <RECORD UID> --name "<FILENAME>" --file-output "<OUTFILE>"`

Optional parameters:

* `-u, --uid <RECORD UID>` UID of the secret to download (Required)
* `--name <FILENAME>` name of the file to download (Required)
* `--file-output <FILENAME | STDOUT | STDERR>` where to write the file's content (Required)
* `--create-folders` create folder for filename path

**Example:**

```
$ ksm secret download -u oxhtLx9qrQIzeSXBtvQj2Q \
   --name "SSHKey.pem" --file-output SSHKey.pem
```

### **delete-attachment**

Delete attachments from secrets in the vault

`ksm secret delete-attachment -u <RECORD UID> -f "<FILE_UID>" -file "<FILENAME>"`

Required parameters:

* `-u, --uid <RECORD UID>` UID of the secret with the attachments (Required)
* `-f, --file <FILENAME|UID>` name or UID of the file to delete (Required)

**Example:**

```
$ ksm secret delete-attachment -u oxhtLx9qrQIzeSXBtvQj2Q \
   --file "SSHKey.pem" --file 8f8IBOqPV58o2r91wVgZ_A
```

### **template**

Display record or field type template information.

#### record

Get the record type schema template and record type list.

`ksm secret template record [-l] [-o json | yaml] [-f OUTPUT FILE] [RECORD TYPE]`

Required one of the following parameters:

`--show-list, -l` Display a list of all available record types.

`RECORD TYPE` - Get the schema template for this record type.

Optional parameter

`--output-format, -o` Output the schema as JSON or YAML. The default is JSON.

`--output-file, -f` Output the schema to a file.

**Example 1:** Gettting a list of record types

```
$ ksm secret template record -l

 Record Type
 ------------------------
 login
 bankAccount
 address
...
```

**Example 2:** Getting the schema for the record type `bankAccount` in YAML.

```
ksm secret template record -o yaml bankAccount

version: v3
kind: KeeperRecord
data:
- recordType: bankAccount
  title: '<#ADD: The title of record here. This is required.>'
  notes: '<#ADD: Add some notes or remove.>'
  fields:
  - type: bankAccount
    value:
      accountType: '<#ADD: Checking | Other | Savings>'
      otherType: '<#ADD: Other Type Description>'
      routingNumber: '<#ADD: Routing Number>'
      accountNumber: '<#ADD: Account Number>'
    privacyScreen: false
  - type: name
    value:
      first: '<#ADD: First Name>'
      middle: '<#ADD: Middle name>'
      last: '<#ADD: Last Name>'
    privacyScreen: false
  - type: login
    value: '<#ADD: Insert a str>'
    privacyScreen: false
  - type: password
    value: '<#ADD: Password or Remove If Generating>'
    privacyScreen: false
    enforceGeneration: false
    complexity:
      length: 64
      caps: 0
      lowercase: 0
      digits: 0
      special: 0
  - type: url
    value: '<#ADD: Insert a str>'
    privacyScreen: false
  - type: cardRef
    value: '<#ADD: Record UID of PaymentCard record.>'
    privacyScreen: false
  - type: fileRef
    value: '<#ADD: Record UID of File record.>'
    privacyScreen: false
  - type: oneTimeCode
    value: '<#ADD: URL starting with otpauth://>'
    privacyScreen: false
```

#### field

Get the field type schema and field type list.

Required one of the following parameters:

`--show-list, -l` Display a list of all available field types.

`FIELD TYPE`- Get the schema for this field type.

Optional parameter

`--output-format, -o` Output the schema as JSON or YAML. The default is JSON.

**Example 1:** Getting a list if field types.

```
$ ksm secret template field -l

Field Type
 ----------------
 accountNumber
 address
 addressRef
...
```

**Example 2:** Get a field type's schema in the default JSON

```
$ ksm secret template field securityQuestion

{
    "type": "securityQuestion",
    "value": {
        "question": "<#ADD: Security Question>",
        "answer": "<#ADD: Answer To The Question>"
    },
    "privacyScreen": false
}
```

### **notation**

Test the magic environmental variable substitution for the `ksm exec` command.

`ksm secret notation <NOTATION FIELD PATH>`

This sub-command allows you to test the environmental variable substitution method by returning the field value through a `keeper://` template URL.

**Example:**

```
$ ksm secret notation keeper://8f8I-OqPV58o2r91wVgZ_A/field/password
ksv#$0sbnb7W@b3VGCHb

$ ksm secret notation keeper://oxhtLx9qrQIzeSXBtvQj2Q/field/password
H=cBcl(u6%Ouv]mXpkPU>u]C;P0>E%yrcML
```

For more details about environmental variable substitution, see the [Exec Command](https://docs.keeper.io/en/keeperpam/secrets-manager/secrets-manager-command-line-interface/exec-command).

{% hint style="info" %}
If your Record UID start with a dash ("-"), add "--" before the UID to get the field with notation\
\
`ksm secret notation -- <RECORD UID>/field/password`
{% endhint %}

### totp

Generate valid pass code from a TOTP field from secret in the vault.

`ksm secret totp <RECORD UID>`

Required parameters:

* `<RECORD UID>` UID of the secret with a TOTP field

**Example:**

```
$ ksm secret totp oxhtLx9qrQIzeSXBtvQj2Q
123456
```

### password

Generate a random password.

`ksm secret password --length <PASSWORD LENGTH> --lc <# OF LOWERCASE CHARS> --uc <# OF UPPCASE CHARS> -d <# OF DIGITS> --sc <# OF SPECIAL CHARACTERS>`

Optional parameters:

{% hint style="info" %}
Either use `--length` or the character group counts (`--lc`, `--uc`, `--digits`, `--sc`). If using the character group counts params, the length will be the total of their values.
{% endhint %}

Overall length. Character group values will automatically be split equally from the length.

* `--length, -l` = Length of password. This will split the length between lowercase, uppercase, digits, and special characters.

Character groups

* `-lc` = Number of lowercase characters.
* `-uc` = Number of uppercase characters.
* `-d` = Number of digits
* `-sc` = Number of special characters.

Example:

```
$ ksm secret password
j.th,D,X92[B;d<F{2IkxuWS={#G4g7=b39kA16v6p44lqBU=v.Y6?MH5}$H3pG4

$ ksm secret password --length 32
5N=%B6ytb9No3w[F7WYgN0V@"+2j!u1#%

$ ksm secret password -lc 10
qaytxkwdwb

$ ksm secret password -lc 2 -uc 2 -d 2 -sc 0
4keD0V
```

### Record UIDs Starting With "-"

If a record UID starts with "-" (dash / hyphen) it needs to be pre-pended with "--" to be used with the KSM CLI.

Example:

`ksm secret get -- -id8QpE2ZAkdd4KlCfoWQ`

*\*The UID in this example is not a real record UID*

See the [Troubleshooting section](https://app.gitbook.com/s/b7weUpu7VBcMnESSH8vG/troubleshooting) for more details


---

# Agent Instructions: 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:

```
GET https://docs.keeper.io/en/keeperpam/secrets-manager/secrets-manager-command-line-interface/secret-command.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.