Fetch Secrets with the CLI

All examples assume we have a Secrets Group called team.project with a Secret MySecret.

Basic Usage

Get the most recent secret

$ strongbox secret get --group team.project --name MySecret

Get a specific version of a secret

$ strongbox secret get --group team.project --name MySecret --version 2

You can of course redirect the value to a file (works for both string and binary secrets)

$ strongbox secret get --group team.project --name MySecret > my.file

Advanced Usage

Strongbox can render the result of a command in different ways using --output {text,json,csv,raw}. Text is the default if nothing is specified. JSON is useful to get an output that closely match that of the Java SDK, e.g. to make use of in a script. raw is intended to extract a single field from the JSON output; this is useful to assign the output directly to a variable. raw can be used in conjunction with --split-output-into-files <path> to store a single field into a separate file per Secret Entry; this is useful to e.g. dump all Secret Values to files.

Output formats

text

This is the default output format. It should NOT be used in scripts since the format can change at any time for what is deemed to be the most human readable.

json

Depending on the command you will either get a JSON blob or a JSON array. This output attempts to closely follow what you would get when using the Java SDK. In general this is the format we recommend when using the CLI in scripts.

Binary encoded secrets will be represented as Base64 encoded strings.

csv

This is intended as an alternative to json for those who find csv to be more convenient. The specific fields to output must be specified with --output-field-names, e.g. --output-field-names secretIdentifier.name,secretValue.secretValue. The field names follow the code structure in the Java SDK. If you misspell a field name, the error message will tell you which fields are allowed in that context.

Binary encoded secrets will be represented as Base64 encoded strings.

raw

This will output a single field specified with --output-field-names as described in the csv output. This field is particularly useful when outputting a secret value.

This will output the secret as is (i.e. no transformation like Base64 encoding).

Examples

Latest Active, JSON output

Fetch latest version of the Secret MySecret in the Secrets Group team.project and output as JSON. Timestamps are outputted as seconds since epoch, UTC.

$ strongbox --output json secret get-latest-active --group team.project --name MySecret
[ {
  "secretIdentifier" : {
    "name" : "MySecret"
  },
  "version" : 2,
  "secretValue" : {
    "encoding" : "utf8",
    "type" : "opaque",
    "secretValue" : "132325"
  },
  "created" : 1479216109,
  "modified" : 1479216109,
  "createdBy" : null,
  "modifiedBy" : null,
  "state" : "enabled",
  "notBefore" : null,
  "notAfter" : null,
  "comment" : null,
  "userData" : null
} ]

Latest Active, Raw output

The raw can output exactly one field of one secret value without any extra characters like newline. This is useful for assigning to variables, piping, etc. The field name follows the same structure as the JSON output, with . between each level. In the previous example we have a nested secretValue inside a secretValue, hence secretValue.secretValue is the id for the field.

$ strongbox --output raw --output-field-names secretValue.secretValue secret get-latest-active --group team.project --name MySecret
132325

All Latest Active, split into files

This is a convenience command to dump all the latest active Secrets into individual files. This is similar to the raw output above, but instead of fetching a single Secret, --all specifies that we want the latest active version of all Secrets in the Secrets Group. The idea of raw output is to be able to store each field individually. Here we achieve that by specifying --split-output-into-files <path> with a path to store each Secret as a separate file.

$ strongbox --output raw --output-field-names secretValue.secretValue --split-output-into-files myPath secret get-latest-active --all --group team.project

This will result in the directory myPath being created if it does not exist. Inside there will be one file for each Secret Entry containing the raw output of the field secretValue.secretValue, i.e. the Secret Value. The name of each file will be <secretName>.<version> - this is to ensure unique names across different commands, as illustrated in the next example.

All Active, split into files

This is the same as the last example, only it fetches all active Versions of each Secret, not only the latest.

$ strongbox --output raw --output-field-names secretValue.secretValue --split-output-into-files myPath secret get-active --all --group team.project

All latest active, as CSV name,value pairs

$ strongbox --output csv --output-field-names secretIdentifier.name,secretValue.secretValue secret get-latest-active --all --group team.project
MySecret1,1234
MySecret2,4321