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.

Installation

Locker Secrets CLI can be downloaded with the following links:

• Windows: https://locker.io/secrets/download/cli-windows

• Linux: https://locker.io/secrets/download/cli-linux

• MacOS (x64): https://locker.io/secrets/download/cli-mac-x64

• MacOS (ARM): https://locker.io/secrets/download/cli-mac-arm64

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]

Credential priority order

Normally, a Locker Secrets 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 Secrets will use those instead.

locker secret list // no access key flags required

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

Global flags

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

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

• --output: set this flag to export the output to an output.txt file in the current working directory.

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]

Common flags between commands secret, environment and scan

• --output [string]: export output to a file specified by path.

• --output-format: specify output format (json, env, txt) (default txt), apply to both terminal and file output.

Common flags between commands secret and environment

• --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 API calls, 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, Java.

• --fetch: set this flag to force Locker Secrets to get encrypted data from the cloud server instead of local storage.

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

Subcommand list

Available on secret and environment commands.

Optional flag:

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

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:

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

Optional flag:

--environment (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} --key {secret's key} --environment {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:

--key, --value (for secret): the key-value pair of secret.

--name (for environment): environment’s name.

Optional flag:

--description: item’s description.

--url: environment’s external URL.

--environment (for secret) specify which environment the secret belongs to.

secret create completed command:

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

Note: the --key and --value flags are required.

environment create completed command:

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

Note: the --name flag is required.

Subcommand update

Available on secret and environment commands.

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

Required flag:

--key (for secret),--name (for environment): specify the targeted item to update.

At least one of the following flags:

--new-key, --new-value, --new-description, --new-environment (for secret), --new-name, --new-url, --new-description (for environment): specify explicitly the field to modify. The environment name passed into --new-environment must exist.

Optional flag:

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

The --new-* flags must be explicitly passed for each field to be modified.

For example, the following secret update command updates the key, value, description and environment of a secret item:

locker secret update --access-key-id {id} --secret-access-key {secret key} --key old_secret_1 --environment old_environment_1  --data --new-key new_secret_1 --new-value new_secret_2 --new-description "this is new secret data" --new-environment new_environment_1 [additional flags]

while this command updates only the key:

locker secret update --access-key-id {id} --secret-access-key {secret key} --key old_secret_1 --environment old_environment_1  --data --new-key new_secret_1 [additional flags]

Note: the key and one of the --new-* flags are required.

environment update completed command:

locker environment update --access-key-id {id} --secret-access-key {secret key} --name old_env_1 --new-name new_env_1 --new-url new_env_2 --new-description "this is new env data" [additional flags]

Note: the name and one of the --new-* flags are required.

Subcommand run

Available on secret commands.

run injects every secret of a given environment as environment variables into a command line process.

Required flag:

--command: the execute command of the targeted process.

Optional flag:

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

secret run completed command:

locker secret run --access-key-id {id} --secret-access-key {secret key} --environment dev --command printenv

Note: the --command flag is required.

Subcommand import

Available on secret commands.

import reads a file containing a list of secrets and imports them to Locker Secret's Vault. Support .env and config.ini data format.

Required flag:

--source: the path to the file containing secrets to be imported.

secret import completed command:

locker secret import --access-key-id {id} --secret-access-key {secret key} --source /path/to/secret/file

Note: the --source flag is required.

Command scan

scan searches a directory and git history (if exists) for exposed secrets.

Required flag:

--source: the path to the directory to be scanned.

scan completed command:

locker scan --source /path/to/code/directory

Note: the --source flag is required.

Subcommand fix

Available on scan commands.

fix performs the scan command, then creates an import file at the target directory containing the import statement and initialization of Locker Secret SDK client (based on the --language flag) and replaces all detected secrets with the SDK’s secret retrieval statement.

Required flag:

--source: the path to the directory to be scanned.

--language: the language of files to be fixed, also determines the SDK to be used (only support python for now).

scan fix completed command:

locker scan fix --source /path/to/code/directory --language python --access-key-id {id} --secret-access-key {secret key}

Note: the --source and --language flags are required.

Error handling

If there is a major problem during execution, Locker Secrets CLI will throw an exception and output an error object in this form:

{
	'object': 'error',
	'error': ERROR_CODE,
	'message': DETAILED_ERROR_MESSAGE
}

Locker Secrets CLI anticipates the following types of ERROR_CODE:

• "command_error": The command or subcommand does not return a valid output.

• "function_error": Go’s standard library encounters an exception.

• "flag_error": User missing one or several required flag for a command or subcommand.

• "input_error": Input data (flag or database’s data) is invalid.

• "invalid_secret_access_key": User’s --access-key-id's data violates the base64 format.

• "data_error": Base64 data is corrupted.

• "server_error": Server’s response for an API call is 5XX.

• "http_error": Server’s response for an API call is of non 5XX errors.

• "path_error": Error during file read/write operation.

• "database_error": Error during database operation.