Overview

Notation is used to pull a value from a secret record. Notation is prefixed with keeper://. The prefix is used to designate that environmental variable contains notation.

The notation is divided into three parts separated by a forward slash.

Record UID / <field|custom_field|file> / Label, Type, or File Name

The first part is the UID of the record.

The second is an enumeration for the three places a value can be stored in a secret.

The third part is how the field is referenced. This is either the field type, label or name of the file. Some fields are complex. They can include multiple values and also dictionaries for the values.

Examples

Below is a record that contains the structure found in a record. The examples will reference this structure.

    $ ksm secret get --title "My Record" --json

    {
        "uid": "Atu8tVgMxpB-iO4xT-Vu3Q",
        "title": "My Database",
        "type": "databaseCredentials",
        "fields": [
            {
                "type": "text",
                "value": [
                    "postgresql"
                ]
            },
            {
                "type": "host",
                "value": [
                    {
                        "hostName": "db.hostname",
                        "port": "5432"
                    }
                ]
            },
            {
                "type": "login",
                "value": [
                    "root"
                ]
            },
            {
                "type": "password",
                "value": [
                    "abc123"
                ]
            },
        ],
        "custom_fields": [
            {
                "label": "Admin Template",
                "type": "text",
                "value": [
                    "template1"
                ]
            },
            {
                "label": "Admin Contact",
                "type": "name",
                "value": [
                    {
                        "first": "John",
                        "middle": "X",
                        "last": "Smith"
                    }
                ]
            },
            {
                "label": "phone",
                "type": "phone",
                "value": [
                    {
                        "number": "555-5555555",
                        "ext": "55",
                        "type": "Work"
                    },
                    {
                        "number": "777-7777777",
                        "ext": "77",
                        "type": "Home"
                    }
                ]
            }
        ],
        "files": [
            {
                "name": "orm.svg",
                "title": "orm.svg",
                "type": "mage/svg+xml",
                "last_modified": 1622044028400,
                "size": 30744
            },
        ]
    }

Example 1 - Simple Values

A simple values is where there is only one literal value for the field. It looks like an array with only one string value. For our Database record type sample, the following will return a single value.

keeper://Atu8tVgMxpB-iO4xT-Vu3Q/field/text
keeper://Atu8tVgMxpB-iO4xT-Vu3Q/field/login
keeper://Atu8tVgMxpB-iO4xT-Vu3Q/field/password
keeper://Atu8tVgMxpB-iO4xT-Vu3Q/custom_field/Admin Template

If you attempt to retrieve a simple value of the field that contains a complex, you will get a JSON value. The notation keeper://Atu8tVgMxpB-iO4xT-Vu3Q/field/host would return {"hostName": "db.hostname", "port": "5432"}.

Also if retrieving a simple value of a field that has multiple values in array will result in only the first item being returned.

Example 2 - Arrays and Dictionaries

Arrays

Some fields contain multiple values. The additional values can be accessed using a index that starts at 0. This means the first value has an index of 0, the second has an index of 1, and so on. The following notation ..

keeper://Atu8tVgMxpB-iO4xT-Vu3Q/custom_field/phone[1]

would return the second item in the array.

{"number": "777-7777777", "ext": "77", "type": "Home"}
Dictionaries

Some values are dictionaries. For example the phone and host fields.

keeper://Atu8tVgMxpB-iO4xT-Vu3Q/custom_field/phone[1][number]
keeper://Atu8tVgMxpB-iO4xT-Vu3Q/custom_field/host[hostName]

To get the specific value in the dictionary, add the key to the notation.

Example 3 - The Full Value

To get the full value, the entire array returned in a JSON format, just use an empty []. The following notation

keeper://Atu8tVgMxpB-iO4xT-Vu3Q/custom_field/phone[]

would return the entire value in a JSON format.

[{"number": "555-5555555", "ext": "55", "type": "Work"}, {"number": "777-7777777", "ext": "77", type": "Home"}]

Example 4 - Files

With notation, you can download files into an environmental variables. This works well with text based files, however mileage may var with binary files. Binary files may cause exceptions to be thrown. Also, there is a limit on the size of the file based on your OS's handling of environmental variables.

keeper://Atu8tVgMxpB-iO4xT-Vu3Q/file/orm.svg