CLI secrets manager that uses the native 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).
- Backup & syncing with iCloud, Google Drive, NextCloud, etc. See iCloud example
- Integration with some browsers and other keychain-compatible software.
demo.mov
Use the install script for an easy, interactive installation by running this command:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/loteoo/ks/main/install)"You can also install ks using homebrew:
brew tap loteoo/formulas
brew install ksManual installation (click to open)
- Download the script file from github.
- Place it into an executable directory that's in your $PATH. For instance,
~/.local/bin/ks - Make sure the file is executable.
chmod +x ~/path/to/ks - Run
ks initto create a first keychain.
Contributor installation (click to open)
Delete any other instance of the ks 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/ks/ks ~/bin/ks
# \
# This should point to the actual ks fileMake sure the file is executable. chmod +x ~/path/to/ks.
Now you can git pull to get updates, modify your running installation and contribute easily.
You can also setup basic completions by adding source <(ks completion) to your shell profile.
Use the ks help command to get an overview of the commands:
$ ks help
Keychain Secrets manager
Usage:
ks [-k keychain] <command> [options]
Commands:
add [-n] <key> [value] Add a secret (-n for note)
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
ks add my-secret 'password123'
# ⚠️ Note that this will add it to your shell history. ⚠️
# Add a secret from your clipboard:
pbpaste | ks add my-secret
# or
ks add my-secret "$(pbpaste)"
# Generate high-entropy secret:
ks rand | ks add my-secret
# or
ks add my-secret "$(ks rand)"
# Mark secret as a "note" to get a multi-line UI in Keychain Access app
cat long-text.txt | ks add -n my-secret-text# Print out secret to stdout
ks show my-secret
# Copy secret to clipboard
ks cp my-secretks rm my-secretks ls
# You can filter with grep:
ks ls | grep 'prefix_'By default, ks uses the Secrets 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 ks. You can pick them on a per-command basis by using the -k argument right after the ks command.
This allows you to pick from which keychain you want to run the ks commands on.
Examples:
# Create a "ProjectA" keychain
ks -k ProjectA init
# Create a "ProjectB" keychain
ks -k ProjectB init
ks -k ProjectA add some-password 'password123'
ks -k ProjectB add some-password 'hunter2'
ks -k ProjectA show some-password
# password123
ks -k ProjectB show some-password
# hunter2You can backup & sync your keychains between computers using cloud syncing software paired with a symlink. Here's an example for iCloud.
- Create a keychain for syncing (Optional)
By default, ks will create a Secrets keychain under ~/Library/Keychains/Secrets.keychain-db. You can use this one for syncing, or create another one. Ex:
# Create a new keychain named iCloud
ks -k iCloud init
- Move the keychain to the iCloud directory
mv "/Users/$USER/Library/Keychains/iCloud.keychain-db" "/Users/$USER/Library/Mobile Documents/com~apple~CloudDocs/iCloud.keychain-db"
- Create a symlink to the keychain under the
~/Library/Keychains/directory
ln -s "/Users/$USER/Library/Mobile Documents/com~apple~CloudDocs/iCloud.keychain-db" "/Users/$USER/Library/Keychains/iCloud.keychain-db"
- Repeat step 3 on every machine that needs syncing
Wait for the file to sync, then recreate the symlink from step 3 on the new computer. Pro tip: you can create and delete a folder to force the refresh of iCloud.
This is for you if:
- You're on macOS.
- You want to store and retrieve secrets using simple commands.
- You want to leverage OS functionnality.
Bonus: You don't like the idea of relying on a HTTP request, a third party server and a credit card subscription to access your secrets.
PRs, issues, comments and ideas are welcome.
Give the repo a star if you like this!
Crafted by millisecond studio ❤️