Locker Secrets features a command-line interface (CLI) that wraps common functionality and formats output. The Locker Secrets CLI is a single static binary. It is a wrapper around the HTTP API.

Locker Secret’s data scheme

There are two types of encrypted data: secret and environment, with each secret belonging to a specific environment (by default the special environment All ). The data follows these two rules to enforce uniqueness:

1. Each environment name must be unique.

2. Each (secret key, environment name) must be unique.

CLI command structure

Each command is represented as a command or subcommand, and there are a number of command and subcommand options available: HTTP options, output options, and command-specific options.

Construct your Locker Secrets CLI command such that the command options precede its path and arguments if any:

locker <command> <subcommands> [flags]

Global flags

• --access-key-id [string]: get from Locker Secret’s web client

• --secret-access-key [string]: get from Locker Secret’s web client

• --headers [strings]: custom headers for Locker Secret Server, must be in the form: “key1: value1, key2: value2”

• --credential [string]: path to the credential file, default $USER/.locker/credential.json

• --api-base [string]: set API endpoint’s host, default https://api.locker.io/locker_secrets

• --agent [string]: specify the invoking agent, default Locker Secret CLI - version xxx, must be in the form of agent - version, currently accepts the following agents: Python, .Net, NodeJS.

• --fetch: set this flag to get encrypted data from the Secret server instead of local storage

• --verbose: display verbose output.

• --output [string]: export the verbose output to a JSON file.

• --resttime [int]: set the desire downtime between API calls to Locker’s server.

• --version: get the version of Locker Secret CLI.

• --help: get the CLI help on the current command/subcommand.

Credential priority order

Normally, a Locker Secret command or subcommand must be supplied with the access key’s ID and secret through two flags:

locker secret list --access-key-id {id} --access-key-secret {secret}

But, if either the environment variables LOCKER_ACCESS_KEY_ID and LOCKER_ACCESS_KEY_SECRET are set or the credential data are initialized either manually or by the configuration command, Locker Secret will use those instead.

locker secret list // no access key flags required

If more than one credential is present, Locker Secret will prioritize by this order: command line flags → credential file → environment variables

Command configuration

Set the access key’s details to the credential file.

locker configuration --access-key-id {id} --secret-access-key {secret key}

There will be an input prompt for either flag that is not provided.

If there is an old access key ID and secret in the credential file, there will be a confirmation prompt to overwrite them.

Command secret

Perform Read and Write actions on encrypted secrets.

locker secret <subcommands> [flags]

Command environment

Perform Read and Write actions on encrypted environments.

locker environment <subcommands> [flags]

Subcommand list

Available on secret and environment commands.

list retrieves and decrypts all secret/environment items from the server.

locker secret list --access-key-id {id} --secret-access-key {secret key} [additional flags]

locker environment list --access-key-id {id} --secret-access-key {secret key} [additional flags]

Subcommand get

Available on secret and environment commands.

get retrieves and decrypts one specific secret/environment item from the server

Required flag:

--name (secret and environment): specify the name/key of the item to decrypt.

Optional flag:

--env (secret only): specify the associated environment of the secret to decrypt, default to null (which represents the All environment) if not provided.

locker secret get --access-key-id {id} --secret-access-key {secret key} --name {secret's name} --env {secret's environment} [additional flags]

locker environment get --access-key-id {id} --secret-access-key {secret key} --name {environment's name} [additional flags]

Subcommand create

Available on secret and environment commands.

create takes input data and generates its encrypted version on Locker Secret’s server.

Required flag:

--data: Specify the to-be-created secret/environment details. It must be in the form of JSON string.

• Secret data:

In JSON form:

{
	"key": "secret_1",
	"value": "secret_2",
	"description": "this is secret data"
}

Completed command:

locker secret create --access-key-id {id} --secret-access-key {secret key} --data "{\"key\": \"secret_1\", \"value\": \"secret_2\",	\"description\": \"this is secret data\"}" [additional flags]

Note: the key and value fields are required.

• Environment data:

In JSON form:

{
	"name": "env_1",
	"external_url": "env_2",
	"description": "this is env data"
}

Completed command:

locker environment create --access-key-id {id} --secret-access-key {secret key} --data "{\"name\": \"env_1\", \"external_url\": \"env_2\",	\"description\": \"this is env data\"}" [additional flags]

Note: the name and external_url fields are required.

Subcommand update

Available on secret and environment commands.

update modifies a secret or environment item’s data by the provided input.

Required flag:

--data: Specify the to-be-created secret/environment details. It must be in the form of JSON string.

--name (secret and environment): specify the targeted item to update.

Optional flag:

--env (secret only): specify the associated environment of the secret to update, default to null (which represents the All environment) if not provided.

• Secret data:

Current decrypted secret data in JSON form:

{
	"key": "old_secret_1",
	"value": "old_secret_2",
	"description": "this is old secret data",
	"environment": "environment_1"
}

Input data in JSON form:

{
	"key": "new_secret_1",
	"value": "new_secret_2",
	"description": "this is new secret data"
}

Completed command:

locker secret update --access-key-id {id} --secret-access-key {secret key} --name old_secret_1 --env environment_1  --data "{\"key\": \"new_secret_1\", \"value\": \"new_secret_2\",	\"description\": \"this is new secret data\"}" [additional flags]

Note: the key and value fields are required

• Environment data:

Current decrypted environment data in JSON form:

{
	"name": "old_env_1",
	"external_url": "old_env_2",
	"description": "this is old env data"
}

Input data in JSON form:

{
	"name": "new_env_1",
	"external_url": "new_env_2",
	"description": "this is new env data"
}

Completed command:

locker environment create --access-key-id {id} --secret-access-key {secret key} --name old_env_1 --data "{\"name\": \"new_env_1\", \"external_url\": \"new_env_2\",	\"description\": \"this is new env data\"}" [additional flags]

Note: the name and external_url fields are required