> ## Documentation Index
> Fetch the complete documentation index at: https://support.locker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets Commands (CLI)

> Guide to using the Locker Secrets command-line interface (CLI)

## 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:

* **Windows**: [https://locker.io/secrets/download/cli-windows](https://locker.io/secrets/download/cli-windows)
* **Linux**: [https://locker.io/secrets/download/cli-linux](https://locker.io/secrets/download/cli-linux)
* **MacOS (x64)**: [https://locker.io/secrets/download/cli-mac-x64](https://locker.io/secrets/download/cli-mac-x64)
* **MacOS (ARM)**: [https://locker.io/secrets/download/cli-mac-arm64](https://locker.io/secrets/download/cli-mac-arm64)

### 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
locker secret <subcommands> [flags]
```

### Environment Command

Perform Read and Write actions on encrypted environments.

```bash theme={null}
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).

```bash theme={null}
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`.

```bash theme={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).

```bash theme={null}
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]
```

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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]
```

```bash theme={null}
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]
```