Skip to main content

​
Secrets Commands (CLI)

Locker Secrets has a command-line interface (CLI) that includes common features and output formatting. The Locker Secrets CLI is a single static binary — a wrapper around the HTTP API.

​
Installation

The Locker Secrets CLI can be downloaded using the links below:

​
Locker Secrets Data Schema

There are two types of encrypted data: secret and environment, with each secret belonging to a specific environment (default is the special All environment). The data follows two rules to enforce uniqueness: each environment name must be unique, and each pair (secret key, environment name) must be unique.

​
CLI Command Structure

Each command is represented as a command or subcommand. Build the CLI command so that command options precede the path and arguments if any: 
locker <command> <subcommands> [flags]

​
Credential Priority Order

Typically, a Locker Secrets command must be provided with the access key ID and secret via two flags: 
locker secret list --access-key-id {id} --secret-access-key {secret}
However, if the environment variables LOCKER_ACCESS_KEY_ID and LOCKER_ACCESS_KEY_SECRET are set or the credential data is initialized using configuration, Locker Secret will use them instead: 
locker secret list // no access key flags required
If more than one credential is provided, Locker Secret will prioritize in the following order: command-line flags → credential file → environment variables.

​
Global flags

  • --version: get the version information of the Locker Secrets CLI.
  • --help: get CLI help for the current command/subcommand.
  • --output: set this flag to output the result to an output.txt file in the current working directory.

​
Configuration Command

Set the access key details in the credential file. 
locker configuration --access-key-id {id} --secret-access-key {secret key}
There will be an input prompt for any flag not provided. If there is an old access key ID in the credential file, there will be a confirmation prompt to overwrite them.

​
Secret Command

Perform Read and Write actions on encrypted secrets. 
locker secret <subcommands> [flags]

​
Environment Command

Perform Read and Write actions on encrypted environments. 
locker environment <subcommands> [flags]

​
Common Command Flags

For secret, environment, and scan commands:
  • --output [string]: export output data to a file specified by the path.
  • --output-format: specify the output format (json, env, txt) — default is txt.
For secret and environment commands:
  • --access-key-id [string]: obtained from the Locker Secrets client.
  • --secret-access-key [string]: obtained from the Locker Secrets client.
  • --headers [strings]: custom headers, must be in the format "key1: value1, key2: value2".
  • --credential [string]: path to the credential file, default is $USER/.locker/credential.json.
  • --api-base [string]: set the server API endpoint, default is https://api.locker.io/locker_secrets.
  • --agent [string]: specify the agent. Must be in the format agent - version, accepts Python, .Net, NodeJS, Java.
  • --fetch: force Locker Secrets to fetch data from the cloud server instead of local storage.
  • --json: format the output data as JSON; if --output is set, the file will be renamed to output.json.
  • --dotenv: use with --output, renames the output file to .env.
  • --resttime [int]: set the idle time between API calls.

​
List Subcommand

Available on secret and environment commands. Fetches and decrypts all items from the server. Optional flag: --environment (for secret) — specifies the related environment, default is null (All environment). 
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]

​
Get Subcommand

Available on secret and environment commands. Fetches and decrypts a specific item from the server. Required flag: --key (for secret) or --name (for environment). Optional flag: --environment (secret only) — default is null. 
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]

​
Create Subcommand

Available on secret and environment commands. Creates an encrypted version of the input data on the server. Required flags: --key, --value (for secret) or --name (for environment). Optional flags: --description, --url, --environment (for secret). 
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]

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]

​
Update Subcommand

Available on secret and environment commands. Modifies the data of a secret or environment. Required flags: --key (for secret) or --name (for environment), and at least one of the --new-* flags. Available --new-* flags: --new-key, --new-value, --new-description, --new-environment (for secret); --new-name, --new-url, --new-description (for environment). Example of a full field update for a secret: 
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]
Example of updating 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]

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]