Secret Command
Retrieve secrets and file attachments from the Keeper Vault

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
get
Get a secret from the vault, or specific fields from a secret
download
Download a vault secret file attachment by name
list
List all secrets associated with the application
notation
Test templating environment variables for the exec command
update
Update a field within an existing secret
totp
Generate pass code from a TOTP field of the secret

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> get specific fields within a secret
  • --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.
The --query switch uses JSONPath, a query syntax based on XPath https://tools.ietf.org/id/draft-goessner-dispatch-jsonpath-00.html
Example 1: Returning a Secret to the console with tabular format
1
$ ksm secret get 8f8I-OqPV58o2r91wVgZ_A
2
3
Record: 8f8I-OqPV58o2r91wVgZ_A
4
Title: Production MySQL Database
5
Record Type: databaseCredentials
6
7
Field Value
8
--------- ----------------------------------------------
9
text MySQL
10
host [{"hostName": "192.168.1.24", "port": "3306"}]
11
login user
12
password ****
13
Copied!
Example 2: Returning a Secret to the console with tabular format and password unmasked
1
$ ksm secret get --unmask --uid 8f8I-OqPV58o2r91wVgZ_A
2
3
Record: 8f8I-OqPV58o2r91wVgZ_A
4
Title: Production MySQL Database
5
Record Type: databaseCredentials
6
7
Field Value
8
--------- ----------------------------------------------
9
text MySQL
10
host [{"hostName": "192.168.1.24", "port": "3306"}]
11
login user
12
password ksv#[email protected]
13
Copied!
Example 3: Retrieving the password field from a secret. There are 2 different methods of doing this.
1
# Using field searching
2
$ ksm secret get -u SNzjw8tM1HsXEzXERCJrNQ -f password
3
4
# Using query syntax
5
$ ksm secret get -u 8f8I-OqPV58o2r91wVgZ_A \
6
--json --query '$.fields[?(@.type=="password")].value'
Copied!
Example 4: Retrieving a particular Custom Field value. There are 2 different methods of doing this.
1
# Using field searching
2
$ ksm secret get -u SNzjw8tM1HsXEzXERCJrNQ -f "API Key"
3
4
# Using query notation
5
$ ksm secret get --uid SNzjw8tM1HsXEzXERCJrNQ \
6
--json --query '$.custom_fields[?(@.label=="API Key")].value'
Copied!
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.
Example 5: Retrieving raw JSON for the individual secret
1
$ ksm secret get --unmask --uid 8f8I-OqPV58o2r91wVgZ_A --json
2
{
3
"uid": "8f8I-OqPV58o2r91wVgZ_A",
4
"title": "Production MySQL Database",
5
"type": "databaseCredentials",
6
"fields": [
7
{
8
"type": "text",
9
"value": [
10
"MySQL"
11
]
12
},
13
{
14
"type": "host",
15
"value": [
16
{
17
"hostName": "192.168.1.24",
18
"port": "3306"
19
}
20
]
21
},
22
{
23
"type": "login",
24
"value": [
25
"user"
26
]
27
},
28
{
29
"type": "password",
30
"value": [
32
]
33
},
34
{
35
"type": "fileRef",
36
"value": []
37
}
38
],
39
"custom_fields": [],
40
"files": []
41
}
Copied!

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:
1
$ ksm secret download -u oxhtLx9qrQIzeSXBtvQj2Q \
2
--name "SSHKey.pem" --file-output SSHKey.pem
Copied!

list

List all secrets associated with the application
ksm secret list
  • --json return in json format
  • --uid <RECORD UID(s)> get specific records by Record UID
Example 1: Tabular format
1
$ ksm secret list
2
3
UID Record Type Title
4
----------------------- -------------------- -------------------------
5
SNzjw8tM1HsXEzXERCJrNQ login Stripe API Key
6
8f8I-OqPV58o2r91wVgZ_A databaseCredentials Production MySQL Database
7
hDFhwSUe6pTWdkJDSRmtBg login Amazon AWS
Copied!
Example 2: JSON format
1
$ ksm secret list --json
2
[
3
{
4
"uid": "SNzjw8tM1HsXEzXERCJrNQ",
5
"title": "Stripe API Key",
6
"record_type": "login"
7
},
8
{
9
"uid": "8f8I-OqPV58o2r91wVgZ_A",
10
"title": "Production MySQL Database",
11
"record_type": "databaseCredentials"
12
},
13
{
14
"uid": "hDFhwSUe6pTWdkJDSRmtBg",
15
"title": "Amazon AWS",
16
"record_type": "login"
17
}
18
]
Copied!

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:
1
$ ksm secret notation keeper://8f8I-OqPV58o2r91wVgZ_A/field/password
3
4
$ ksm secret notation keeper://oxhtLx9qrQIzeSXBtvQj2Q/field/password
5
H=cBcl(u6%Ouv]mXpkPU>u]C;P0>E%yrcML
Copied!
For more details about environmental variable substitution, see the Exec Command.

update

Update a field within an existing secret
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.
    If there are duplicate labels on a custom fields, only the top most field will be updated.
The format of --field and --custom-field parameters value is a key and field value join together with the '=' character. If a key or field value contains a '=', the '=' in the key or field needs to be escaped with a '\' character.
Example 1: Basic use case
1
# Update the password for a secret
2
$ ksm secret update --uid XXXXX --field "password=xxxxxxxxxxx"
3
4
# Update a custom field value
5
$ ksm secret update --uid XXXXX --custom-field "My Custom Label=XXXXX"
Copied!
Example 2: If a key or field values contains a space, the entire parameter value needs to be wrapped in quotes.
1
# key is "=ONE=", value="Step 1"
2
$ ksm secret update --uid XXXXX --custom-field "\=ONE\==Step 1"
3
4
# key is "ODD\", value="EDGECASE"
5
$ ksm secret update --uid XXXXX --custom-field "ODD\\=EDGECASE
Copied!

totp

Generate valid pass code from a TOTP field from secret in the vault.
ksm secret tot <RECORD UID>
Required parameters:
  • <RECORD UID> UID of the secret with a TOTP field
Example:
1
$ ksm secret totp oxhtLx9qrQIzeSXBtvQj2Q
2
123456
Copied!
Last modified 1mo ago