1Password command-line tool: Secrets Automation alpha release

Introducing: Secrets Automation commands ^[ALPHA]

We’re introducing 3 brand new commands that you can use to load secrets from 1Password into your applications:

• op run - Load secrets into your application as environment variables
• op read - Fetch a secret using the secrets reference syntax
• op inject - Inject secrets into a templated config file

How does the term ‘secret’ relate to your 1Password items? They either refer to the value of a 1Password item field (for database passwords, API keys, and so on) or to the contents of a file (for SSH, TLS, or GPG keys, for example).

Secrets Reference Syntax

The new commands are geared specifically towards the secrets management use case. To keep your app configuration changes as lightweight as possible, we’re also introducing a new syntax with these commands so you can do inline replacements of plaintext secrets with an op:// reference URI.

Here’s how these references are composed:

To resolve these references with the corresponding secret values and load those into your apps, you can use the command-line tool ^[ALPHA]. You can load them as environment variables using op run to load, or injecting secrets into config files using op inject.

Having replaced the senstive portion of your configuration with references, you can safely check your configuration code into Git!

A note on item naming

Though technically not enforced, we do recommend naming your 1Password items in a way that is both ‘terminal friendly’ and URI friendly. So use dashes or underscores instead of spaces and stay away from special characters.

Also, keep in mind that if there’s multiple item name or field name matches, the command-line tool won’t assume which value you really meant to choose, so you’ll get back an error instead.

op run

op run [flags] -- <command>

You can use the run command to load secrets into environment variables of a subprocess.

It scans environment variables for secret references, loads the corresponding values from 1Password, and runs the provided command in a subprocess with the secrets made available as environment variables for the duration of the subprocess.

Masking

If your subprocess accidentally prints secrets to stdout, these secrets will automatically be concealed by the masker that comes with the run command. When a secret is detected, you’ll see <concealed by 1Password> appear in your logs in lieu of the sensitive value.

Flags

Examples

• Print a secret with and without masking

  {
    $ export DB_PASSWORD=op://app-prod/db/password
  
    $ op run -- printenv | grep DB_PASSWORD
    DB_PASSWORD=
  
    $ op run --no-masking -- printenv | grep DB_PASSWORD
    DB_PASSWORD=fX6nWkhANeyGE27SQGhYQ
    }

• Load secrets into an application

  Here’s an example Node.js app that needs to connect to a database:

  {
    $ node app.js
    [INFO]  Launching Node.js app...
    [ERROR] Missing credentials DB_USER and DB_PASSWORD
    [INFO]  Exiting with code 1
    }

  Now, set some secret references in your environment:

  $ export DB_USER=op://app-dev/db/user
  $ export DB_PASSWORD=op://app-dev/db/password
  

  And wrap the command with op run:

  {
    $ op run -- node app.js
    [INFO]  Launching Node.js app...
    [DEBUG] ✔ Connected to db as user 'mydbuser' with password ''
    }

op read

{
op read [flags] op:///[/
]/
}

For one-off secret reads, you can use the read command, which will output the plaintext value of a single secret. This can come off handy when writing shell scripts, CI/CD configuration, or for quick terminal access.

You can also write it to a file using the -o/--out-file flag.

Flags

Examples

• Get a database password

  $ op read op://app-prod/db/password
  fX6nWkhANeyGE27SQGhYQ
  

  Coming from vault app-prod, item db, and field password.

• Download an SSH key

  {
    $ op read -o $HOME/.ssh/key.pem --file-mode 0600 op://app-infra/server/ssh/key.pem
    /home/wendyappleseed/.ssh/key.pem
    }

  Coming from vault app-infra, item server, section ssh, and field with filename key.pem.
  The -o flag causes the output value to be the file path instead of the secret value.

op inject

op inject [flags]

To load secrets into a config file, you can use the inject command.

Pass in a templated config file with secret references, and receive a resolved config file with the corresponding secret values in place. Specify secrets in your templates using their reference URIs, wrapped in double curly braces:

db_password: {{ op://app-prod/db/password }}

By default, inject takes its input from stdin and outputs the result to stdout. To read the input from a file instead, you can use the -i/--in-file flag and the -o/--out-file flag to specify where the sensitive output should be written to.

Flags

Examples

• Inject secrets into a config template from stdin

  {
    $ echo "db_password: {{ op://app-prod/db/password }}" | op inject
    db_password: fX6nWkhANeyGE27SQGhYQ
    }

• Inject secrets into a config template file

  {
    $ cat config.yml.tpl
    db_address: {{ op://app-prod/db/host }}:1234
    db_password: {{ op://app-prod/db/password }}
  
    $ op inject -i config.yml.tpl -o config.yml && cat config.yml
    db_address: database.internal:1234
    db_password: fX6nWkhANeyGE27SQGhYQ
    }

  Though not required, you can add a .tpl extension to the input file to distinguish the template file from the final config file that your app can actually use.

Installing on your local workstation

To install the alpha command-line tool on your local workstation, download the right binary for your platform:

This alpha release can act as a replacement for your current 1Password command-line tool installation and does not touch the existing command signature.

Authentication

To provision secrets to applications that run locally, you can use the op signin command to authenticate with your 1Password account password.

Installing on a server

To use the Secrets Automation features in a remote environment (Linux, cloud, on-prem, and so on), here’s an example oneliner to install the command-line tool on a Linux host:

{
curl -sSfo op.zip \
  https://bucket.agilebits.com/cli-private-beta/v2/op_linux_amd64_v2-alpha1.zip \
  && unzip -od /usr/local/bin/ op.zip \
  && rm op.zip
}

We also provide a Dockerfile that you can use as an example to build the command-line tool into a Docker image to push to your registry:

{
curl -sSfO https://bucket.agilebits.com/cli-private-beta/v2/Dockerfile
docker build -t ${YOUR_DOCKER_REGISTRY}/1password/op:v2-alpha1 .
docker push ${YOUR_DOCKER_REGISTRY}/1password/op:v2-alpha1
}

Authentication

To provision secrets to apps, first set up a 1Password Connect server in your infrastructure and issue a token that has read access to the relevant vaults.

The run, inject and read commands will automatically switch to use the Connect server if the following environment variables have been configured:

• OP_CONNECT_TOKEN - A token to authenticate to 1Password Connect
• OP_CONNECT_HOST - The URL where your 1Password Connect instance is hosted

Note on the alpha builds

The Secrets Automation features in the command-line tool are still in alpha stage and are not intended for wide production use yet, because some things may change before this reaches GA.

When it does reach GA, we won’t remove the alpha builds right away, but you should expect having to upgrade your install scripts to use a stable download link sooner or later.