Skip to main content

Quick, simple AWS Parameter Store CLI for listing/reading params with tab completion

Project description

Quick, simple AWS Parameter Store CLI for listing/reading params with tab completion

screen recording of psread usage example


The AWS-provided tools for using Parameter Store (the web UI and awscli) are fine if you know exactly what you’re trying to find. They’re not so good if you’re… looking… for something, and want to explore your Parameter Store parameters like a filesystem, or hierarchical datastore. This is a dead-simple, quick, and rather ugly hack of a CLI built in Python and largely inspired by the Hashicorp Vault CLI, plus shell completion for parameter paths. This doesn’t write parameters or do other “fancy” things. It’s mainly intended for teams who are also using Parameter Store to replace human-centered secret stores (i.e. Vault, KeePass, random encrypted files, etc.) and often have only a vague idea of the exact parameter name they’re looking for.


This is a somewhat-tipsy Friday evening quarantine project. There are (it’s almost painful to write this) no unit tests, and it’s largely cargo-culted from previous work of mine. I’ll gladly accept PRs assuming they look correct, meet PEP8/PyFlakes style, and are relatively straightforward and working. That’s about the end of “support”.


This project requires Python 3.6 or later, as it makes use of both PEP484 type hints and PEP498 f-strings. It also requires boto3, argcomplete, and appdirs.


psread can be installed with pip install psread or python -mpip install psread

To set up autocompletion in your shell, either activate global completion for argcomplete, or for bash, set up completion for this project specifically. To do that in just your current shell:

eval "$(psread --bash-wrapper)"

To do that permanently (recommended):

echo -e "eval \"\$($(which psread) --bash-wrapper)\"" >> ~/.bashrc


There are two main functionalities: listing parameters and reading parameters. Shell tab completion is included, primarily for bash, via the argcomplete package.

$ psread -h
usage: psread [-h] [-v] [-w] [-V] [-R] [--called-from-wrapper] [{ls,list,read,get}] [PARAM]

Quick, simple AWS Parameter Store CLI for listing/reading params with tab completion

positional arguments:
  {ls,read,get}         Action to perform
  PARAM                 Parameter (or parameter path) to list or read

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         verbose output. specify twice for debug-level output.
  -w, --bash-wrapper    print bash wrapper function to STDOUT and exit
  -V, --version         Print version number and exit
  -R, --recache         re-cache parameters for this region of this account
                        DO NOT USE

Parameter Caching

psread caches the Names (and only the names) of all parameters in each region of each account that you use it with; this is effectively required for sane tab-completion speeds. The parameters are cached in a Pickle file at a platform-specific path, which can be seen in the psread -V output. This path can be overridden with the PSREAD_CACHE_PATH environment variable, which should specify the absolute path to write the pkl file at.

By default, parameter names are cached for 86400 seconds (1 day); this can be overridden by setting the PSREAD_CACHE_TTL environment variable to an integer cache TTL in seconds.

Re-caching of the current region of the current account can be forced by running psread with the -R or --recache option.


In order to enable debug logging before normal command-line options and arguments are parsed, such as during tab completion: export PSREAD_LOG=DEBUG

Release Process

Completely manual right now:

  1. Bump the version in and update the Changelog.

  2. python sdist && python bdist_wheel

  3. twine upload dist/*

  4. git push

  5. git tag -s -a X.Y.Z -m 'X.Y.Z released YYYY-mm-dd' && git tag -v X.Y.Z && git push origin X.Y.Z

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

psread-0.1.2.tar.gz (8.4 kB view hashes)

Uploaded Source

Built Distribution

psread-0.1.2-py2.py3-none-any.whl (20.9 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page