secret

README

Secret - A simple cli for macOS Keychain

The secret utility is a small command line application that provides a simplified interface to the macOS Keychain. It doesn't have many features, but does provide a simiple, opinionted interface to Keychain for scripting purposes.

Usage

Generate a Password

Use the gen command to create a random password:

secret gen

Example output:

sM9au9TILcId$}qk

By default, the gen command will output a 16 character, random password, containing 2 digits and 2 symbols. However, the password can be customized with some options.

To generate a really insecure password:

secret gen --length 8 --digits 0 --symbols 0 --no-upper --no-repeats

Example output:

vmbiyrgx

The gen command can also be used in environment variables or piped to the clipboard.

Use in an environment variable:

MY_SECRET=$(secret gen)

Pipe to the clipboard:

secret gen | pbcopy

Set a Secret

The set command is used to create a new secret or update an existing secret on the Keychain. If a secret does not exist yet, then the set command will create a new secret with the username from the $USER enviroment variable and an automatically generated password using the same options as the gen command.

Create a new secret called foobar:

secret set foobar

If you want to be specify your own password you can use the --ask option to be prompted for a password. The --ask option doesn't currently prevent you from entering an insecure password or check password complexity so becareful.

Create a new secret with a user defined password:

secret set --ask foobar

If the secret already exists, the set command will prompt you before updating the secret with a new password. If you don't want to be prompted, you can force the set command to update the password without prompting using the --update option.

Update a secret without prompting:

secret set --update foobar

If you want to create a secrete with a username other than the username that you are logged into as, use the --user option to specify the username for the secret.

Create secret with a different username:

secret set --user=bob foobar

Get/Copy a Secret

Once you have stored a secret on the Keychain you can use the get command to retrieve it and print it to STDOUT or use the copy command to copy it to the clipboard.

Print password to STDOUT:

secret get foobar

Copy to password to clipboard:

secret copy foobar

Like the gen command, the get command works well with environment variables or other command line utilities.

Use secret with the restic backup utility:

RESTIC_PASSWORD_COMMAND=secret get resticbackup

List Secrets

You can use the list command to list all secrets stored in the Keychain. You can further refine the search using the --user option to filter secrets with just that username.

List all secrets:

secret list

List all secrets using the username bob:

secret list --user=bob

How It works

The secret utility uses the github.com/keybase/go-keychain/keychain package to store a username/password pair in the macOS Keychain. This package uses cgo bindings to the native Keychain library for the Keychain manipulation. The secret is stored as a Generic Password (man security for details).

The description field (also called the kind) is set to secret. This makes searching the Keychain for passwords set using this utility possible (the default kind is 'application password').

The account field is set (by default) to the $USER environment variable (which is typically the logged in user). The service field is used as the name of the secret and the label field (which is called Name in the Keychain Access application) is set to 'account@service'.

The commands and switches were designed so that for most workflows, the defaults should work fine.