stow

Command-line secrets manager for Summon powered by the Keychain tools already available on macOS systems.

It's a tiny, straightforward CLI that let's you securely store and retrieve encrypted secrets without any additional third parties involved.

It's built as a small wrapper around the native security command, so it's fast, secure, works offline and is fully interoperable with macOS keychains, which give you:

A nice, built-in UI to manage your secrets (Keychain Access app).
Optional backups, syncing and sharing with iCloud Keychain.
Integration with some browsers and other keychain-compatible software.

Installation

Install script

Use the install script for an easy, interactive installation by running this command:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/infamousjoeg/stow/main/install)"

Homebrew

You can also install stow using homebrew:

brew tap infamousjoeg/tap
brew install stow

Manual installation

Download the script file from github.
Place it into an executable directory that's in your $PATH. For instance, ~/.local/bin/stow
Make sure the file is executable. chmod +x ~/path/to/stow
Run stow init to create a first keychain.

Contributor installation

Delete any other instance of the stow script on your machine.

Clone this repo somewhere on your machine, then create a symlink in a bin folder to the script:

#         This directory should be in your executable PATH
#                              /
ln -s ~/path/to/repo/stow/stow ~/bin/stow
#                        \
#       This should point to the actual ks file

Make sure the file is executable. chmod +x ~/path/to/stow.

You can also setup basic completions by adding source <(stow completion) to your shell profile.

Usage

Use the stow help command to get an overview of the commands:

$ stow help
stow 0.5.0

Usage:
  stow [-k keychain] <command> [options]

Commands:
  add [-n] <key> [value]    Add a secret (use -n for multiline notes)
  show <key>                Decrypt and reveal a secret
  cp <key>                  Copy secret to clipboard
  rm <key>                  Remove secret from keychain
  ls                        List secrets in keychain
  rand [size]               Generate random secret
  init                      Initialize selected keychain
  help                      Show this help text
  version                   Print version

Add secrets

stow add aws/access_key_id 'AKIAGRQDQWERTYUIOP'
# ⚠️ Note that this will add it to your shell history. ⚠️

# Add a secret from your clipboard:
pbpaste | stow add aws/access_key_id
# or
stow add aws/access_key_id "$(pbpaste)"

# Generate high-entropy secret:
stow rand | stow add dev/testuser
# or
stow add dev/testuser "$(stow rand)"

# Mark secret as a "note" to get a multi-line UI in Keychain Access app
cat ~/.cybr/config | stow add -n cybr/config

Retrieve secrets

# Print out secret to stdout
stow show aws/access_key_id

# Copy secret to clipboard
stow cp aws/access_key_id

Remove secrets

stow rm aws/access_key_id

List secrets

stow ls

# You can filter with grep:
stow ls | grep 'aws/'

Using multiple keychains

By default, stow uses the Summon keychain.

You can change this permanently by exporting a KS_DEFAULT_KEYCHAIN environment variable in your shell profile. Ex: export KS_DEFAULT_KEYCHAIN="AlternateKeychain"

You can also work with multiple keychains with stow. You can pick them on a per-command basis by using the -k argument right after the stow command.

This allows you to pick from which keychain you want to run the stow commands on.

Examples:

# Create a "ProjectA" keychain
stow -k ProjectA init

# Create a "ProjectB" keychain
stow -k ProjectB init

stow -k Summon add some-password 'supersecret'
stow -k ProjectA add some-password 'password123'
stow -k ProjectB add some-password 'hunter2'

stow -k Summon show some-password
# supersecret
stow -k ProjectA show some-password
# password123
stow -k ProjectB show some-password
# hunter2

infamousjoeg / stow