Package: keycmd
keycmdPrefix any command withkeycmdto safely source your secrets and credentials from the OS keyring, instead of risky.envfiles (or worse 🙈). Common applications include npm, pip, poetry, docker, docker compose and kubectl!Supports Windows, macOS and Linux.AboutThe main functionality ofkeycmdis to load secrets from your OS keyring and expose them as environment variables for the duration of a single shell command or alternatively for the lifetime of a subshell.This enables you to store sensitive data such as authentication tokens and passwords in your OS keyring, so you no longer need to rely on insecure practises such as.envfiles, or pasting secrets into your terminal. 😱The most common use case is to load credentials for package managers such as pip and npm when using private package indexes, such as Azure Artifact Feeds. Another common use case is docker build secrets.InstallationNoteIf you're intending to installkeycmdin a WSL or pyenv environment, you'll have to skip ahead to the specific installation instructions for those environments.Global installationInstallkeycmdfrom pypi usingpip install keycmd, or whatever alternative python package manager you prefer.Note that the executablekeycmdhas to be installed to a folder that is on yourPATHenvironment variable, or the command won't be available globally. Assuming you were able to runpipjust now, thekeycmdexecutable should end up in the exact same location and everything should be fine.To verify keycmd is installed and available, runkeycmd --version.pyenv installationNow, if you're using pyenv, you're going to have to jump through a few hoops since keycmd needs to be installed globally, which flies directly into the face of what pyenv is trying to accomplish.This guide assumes you've also installedpyenv-virtualenv, in order to get you the cleanest of setups. ✨NoteThese pyenv instructions are for pyenv on Linux and MacOS. If you are using pyenv-win on Windows, these instructions are most likely not 100% compatible with your setup.Run the following commands one by one to install keycmd into its own standalone environment:# run the following commands one by onepyenvvirtualenv3.9keycmd
pyenvactivatekeycmd
pipinstallkeycmdpathToKeycmd=$(python-c'import sys; from pathlib import Path; print(Path(sys.executable).parent / "keycmd")')pyenvdeactivate
mkdir-p$HOME/.local/bin
ln-s$pathToKeycmd$HOME/.local/bin/keycmdFinally, edit your~/.bashrcfile (or whatever shell profile you use) to include~/.local/binin yourPATHvariable:exportPATH="$HOME/.local/bin:$PATH"NoteThis line may already be in place in your~/.bashrc, for example, if you installed poetry! It's a common trick used to expose specific binaries onPATHwhen they are in folders that also include binaries that shouldnotbe exposed onPATH.To verify keycmd is installed and available, runkeycmd --version.WSL installationIf you're using WSL, you'll run into a wall when you first try to use keycmd. That's because keycmd uses the keyring library to connect to OS keyrings, and keyring will attempt to connect to your linux distro's (probably Ubuntu) keyring background service, which by default isn't actually running in a WSL environment!If you did actually set up your linux distro's keyring background service, that's fine, you can continue using it and don't need to perform any additional steps.NoteJust because you installed WSL on your system, does not mean you are actually working in WSL. Think about this for a moment; are you using Python from Windows or from WSL? The instructions here are only necessary if you are actually working in WSL.So, if you would like keyring to connect from the WSL environment to your Windows Credential Manager instead, continue with the next steps.You have to install keycmd according to the above instructions (globally, or with pyenv)in Windows, not in WSL. Then, assumingkeycmdis on your WindowsPATH, it should now be available in WSL as well!Up- and downgradingIf at a later point in time, you want to install a different version of keycmd, just use pip again.NoteIf you're using pyenv, make sure to activate the virtual environment first withpyenv activate keycmd. Don't forget topyenv deactivateafterwards.To upgrade to latest:pip install -U keycmdTo install a specific version:pip install keycmd==0.6.0QuickstartNow that keycmd is installed, we can perform a quick test to see how it works!Let's add a new key to our OS keyring, and then see how we can expose it with keycmd.For the purpose of this example, usemy-secretas the credential name andmy-usernameas the... username. I usedfoobaras the password.On Windows, that means clicking Start and typing "Credential Manager" to find the app. Click the Windows Credentials tab, and click "Add a generic credential". See the screenshots below.On macOS, open Keychain Access (Command-Space bar, typekeychain access), then press Command-N to add a
new password item. Please note that Account Name holds the username.NotePull requests to add visual guides for linux keyrings are most welcome!Now, create a.keycmdconfig file in your user home folder. Put the following configuration in the file and save:[keys]SECRET={credential="my-secret",username="my-username"}Finally, open a terminal and run a command to print the secret, so we can see if it worked. That's going to look different depending on what shell you're using, so here's a couple examples:Cmd:keycmd echo %SECRET%Powershell:keycmd 'echo $env:SECRET'Bash:keycmd 'echo $SECRET'You should see the textfoobarbeing printed to the terminal.You've successfully set up keycmd! 👏See theadvanced configuration examplebelow for a more involved usecase for keycmd, where poetry, npm and docker-compose are all put together.UsageThe CLI has the following options:❯ keycmd --help
usage: keycmd [-h] [-v] [--version] [--shell] ...

positional arguments:
  command        command to run

optional arguments:
  -h, --help     show this help message and exit
  -v, --verbose  enable verbose output, useful for configuration debugging
  --version      print version info
  --shell        spawn a subshell instead of running a commandThere are two main ways to use the CLI:keycmd 'your command'keycmd --shellThe first is the most preferred method, since your secrets will only be exposed as environment variables during a one-off command. The latter is less preferable, but can be convenient if you are debugging some process that depends on the credentials you are exposing.ConfigurationNoteif you are having trouble configuring keycmd, refer to sectiondebugging configuration.LocationsConfiguration can be stored in three places (where~is the user home folder and.is the current working directory when callingkeycmd):~/.keycmdall.keycmdfound while walking file system up from.firstpyproject.tomlfound while walking file system up from.Note:The search for.keycmdandpyproject.tomlwill stop at the root of a git repository, and before the user home folder, to ensure your configuration can be applied locally to subtrees of your filesystem.Configuration files are loaded and merged in the listed order.OptionsThe options schema is defined as follows:keys: dict{key_name}: dictcredential: strusername: strb64: bool, optionalformat: str, optionalaliases: dict{alias_name}: dictkey: strb64: bool, optionalformat: str, optionalYou can define as many keys as you like. For each key, you are required to define:thekey_name, which is the name of the environment variable under which the credential will be exposedthecredential, which is the name of the credential in your OS keyringtheusername, which is the name of the user owning the credential in the OS keyringOptional fields:b64, set this totrueto apply base64 encoding to the passwordformat, apply a format string (before optionally applying base64 encoding)you have access tocredential,usernameandpasswordso for example you can put together a basic auth header like this:"{username}:{password}"The aliases make it possible to expose the same credentials in another way, the fields work the same.ExampleThis configuration exposes a specific credential both plainly under the environment variableMY_TOKEN, and again with base64 encoding applied asMY_TOKEN_B64:[keys]MY_TOKEN={credential="MY_TOKEN",username="azure"}[aliases]MY_TOKEN_B64={key="MY_TOKEN",b64=true}pyproject.toml exampleYou can also store your configuration inpyproject.toml, by prefixing the keys withtool.keycmd. So if we were to convert the previous example it would look like this:[tool.keycmd.keys]MY_TOKEN={credential="MY_TOKEN",username="azure"}[tool.keycmd.aliases]MY_TOKEN_B64={key="MY_TOKEN",b64=true}OpenAI exampleWith OpenAI, you're instructed touse an API keyto authenticate with their APIs. When you put that string in a.envfile, or directly in your code, you risk sharing your API key with the world! 🙅‍♂️Instead, just put it in your OS keyring, and expose it with keycmd when you run your python scripts or jupyter notebooks.For example, if you add it to your OS keyring under the namemy-openai-tokenandyour-username, you would use the following.keycmdconfiguration:[keys]OPENAI_API_KEY={credential="my-openai-token",username="your-username"}Now you can run any OpenAI script by just prefixing your commands withkeycmd. For example:keycmd'python my_openai_script.py'Or a jupyter notebook:keycmd'jupyter notebook'That's all! 🤘 Now you can rest easily, knowing your tokens are safe. 🛌💤Advanced exampleThis is an example configuration for Poetry, npm and docker-compose. It should inspire you to see the possibilities keycmd provides thanks to its configuration system.In this case, we are authenticating with an Azure DevOps Personal Acces Token to an Azure Artifacts Feed which serves both python and node.js packages.Let's begin by creating a Packaging (Read) token in Azure DevOps:Make sure to check the Packaging (Read) permission, it's the only permission we need for this example.In this case, we won't enter it into the OS keyring manually. We'lllet Poetry handle it. Let's review ourpyproject.tomlfile:[tool.poetry]name="my-project"version="1.0.0"description=""authors=["My Name <my-name@my-organization.com>"][[tool.poetry.source]]name="main"url="https://pkgs.dev.azure.com/my-organization/_packaging/main/pypi/simple/"priority="default"[tool.poetry.dependencies]python="~3.9"[build-system]requires=["poetry>=1.0.0"]build-backend="poetry.core.masonry.api"Looks like our poetry source is namedmain, so let's run the appropriate command:poetry config http-basic.main <username> <personal-access-token>Poetry will create an entry in the OS keyring, and when you runpoetry installit will automatically authenticate using that credential. No need forkeycmdhere!Next, we're going to piggyback off this credential with keycmd, to reuse it for npm, and for docker-compose. That way, we only have 1 credential to manage (that means updating it when it expires).Look up the new credential in your OS keyring, and store the following configuration in a.keycmdfile. Of course,review your OS keyring and adjust your configuration to match the credential name and username![keys]PAT={credential="credential-name",username="your-username"}PAT_B64={credential="credential-name",username="your-username",b64=true}In this example, we are exposing the same credential twice:As the environment variablePATAgain but with base64 encoding applied as the environment variablePAT_B64This is important, because npm requires that we supply the token with base64 encoding, but other tools do not.For my npm project, I have a.npmrcfilewith the following contents:registry=https://pkgs.dev.azure.com/my_organization/_packaging/main/npm/registry/
always-auth=true
//pkgs.dev.azure.com/my_organization/_packaging/main/npm/registry/:username=dev
//pkgs.dev.azure.com/my_organization/_packaging/main/npm/registry/:_password=${PAT_B64}
//pkgs.dev.azure.com/my_organization/_packaging/main/npm/registry/:email=email
//pkgs.dev.azure.com/my_organization/_packaging/main/npm/:username=dev
//pkgs.dev.azure.com/my_organization/_packaging/main/npm/:_password=${PAT_B64}
//pkgs.dev.azure.com/my_organization/_packaging/main/npm/:email=emailNow, I can set up mynode_modulesjust by callingkeycmd 'npm install'! 🚀Notenpm will complain if you make any calls such asnpm run [...]without the environment variable set. 🙄 You can set them to the empty string to make npm shut up. I useexport PAT_B64=(orsetx PAT_B64=on Windows).Additionally, I also have a docker-compose file in this project which is configured as follows:secrets:
  token:
    environment: PAT
  token_b64:
    environment: PAT_B64When I callkeycmd 'docker compose build'these two variables are exposed by keycmd and subsequently they are available asdocker compose build secrets. 👌Debugging configurationIf you're not getting the results you expected, use the-vflag
to debug your configuration. Keycmd will verbosely tell you about all the steps it's taking.Here's an example using cmd.exe, otherwise, the command would bepoetry run keycmd -v 'echo $ARTIFACTS_TOKEN_B64':❯ poetry run keycmd -v echo %ARTIFACTS_TOKEN_B64%
keycmd: loading config file C:\Users\kvang\.keycmd
keycmd: loading config file C:\Users\kvang\dev\keycmd\pyproject.toml
keycmd: merged config:
{'keys': {'ARTIFACTS_TOKEN': {'credential': 'korijn@poetry-repository-main',
                              'username': 'korijn'},
          'ARTIFACTS_TOKEN_B64': {'b64': True,
                                  'credential': 'korijn@poetry-repository-main',
                                  'username': 'korijn'}}}
keycmd: exposing credential korijn@poetry-repository-main belonging to user korijn as environment variable ARTIFACTS_TOKEN (b64: False)
keycmd: exposing credential korijn@poetry-repository-main belonging to user korijn as environment variable ARTIFACTS_TOKEN_B64 (b64: True)
keycmd: detected shell: C:\Windows\System32\cmd.exe
keycmd: running command: ['C:\\Windows\\System32\\cmd.exe', '/C', 'echo', '%ARTIFACTS_TOKEN_B64%']
aSdtIG5vdCB0aGF0IHN0dXBpZCA6KQ==Note on keyring backendsSince keycmd uses keyring as its backend, you're not limited to just working with OS keyrings. 🤯 Any keyring backend will work with keycmd. No special configuration required!See thethird party backendslist for all options.