Skip to content
/ ssmsh Public

A shell for the EC2 Parameter Store


Notifications You must be signed in to change notification settings


Repository files navigation


ssmsh is an interactive shell for the EC2 Parameter Store. Features:

  • Interact with the parameter store hierarchy using familiar commands like cd, ls, cp, mv, and rm
  • Supports relative paths and shorthand (..) syntax
  • Operate on parameters between regions
  • Recursively list, copy, and remove parameters
  • Get parameter history
  • Create new parameters using put
  • Advanced parameters (with policies)
  • Supports emacs-style command shell navigation hotkeys
  • Submit batch commands with the -file flag
  • Inline commands



Download binaries for MacOS, Linux, or Windows from the latest release here.


There is a Homebrew tap published to this repo, for installation on both MacOS and Linux. Add the tap and install with:

brew tap bwhaley/ssmsh
brew install ssmsh


There is also a Nix package available for MacOS and Linux:

nix-env -i ssmsh


Set up AWS credentials.

You can set up a .ssmshrc to configure ssmsh. By default, ssmsh will load ~/.ssmshrc if it exists. Use the -config argument to set a different path.


A few notes on configuration:

  • When setting the region, the AWS_REGION env var takes top priority, followed by the setting in .ssmshrc, followed by the value set in the AWS profile (if configured)
  • When setting the profile, the AWS_PROFILE env var takes top priority, followed by the setting in .ssmshrc
  • If you set a KMS key, it will only work in the region where that key is located. You can use the key command while in the shell to change the key.
  • If the configuration file has output=json, the results of the get and history commands will be printed in JSON. The fields of the JSON results will be the same as in the respective Go structs. See the Parameter and ParameterHistory docs.



/> help

cd           change your relative location within the parameter store
clear        clear the screen
cp           copy source to dest
decrypt      toggle parameter decryption
exit         exit the program
get          get parameters
help         display help
history      get parameter history
key          set the KMS key
ls           list parameters
mv           move parameters
policy       create named parameter policy
profile      switch to a different AWS IAM profile
put          set parameter
region       change region
rm           remove parameters

List contents of a path

Note: Listing a large number of parameters may take a long time because the maximum number of results per API call is 10. Press ^C to interrupt if a listing is taking too long. Example usage:

/> ls
/> ls -r
/> ls /dev/app

Change dir and list from current working dir

/> cd /dev
/dev> ls

Get a parameter

/> get /dev/db/username
  ARN: "arn:aws:ssm:us-east-1:012345678901:parameter/dev/db/username",
  LastModifiedDate: 2019-09-29 23:22:19 +0000 UTC,
  Name: "/dev/db/username",
  Type: "SecureString",
  Value: "foo",
  Version: 1
/> cd /dev/db
/dev/db> get ../app/url
  ARN: "arn:aws:ssm:us-east-1:318677964956:parameter/dev/app/url",
  LastModifiedDate: 2019-09-29 23:22:49 +0000 UTC,
  Name: "/dev/app/url",
  Type: "SecureString",
  Value: "",
  Version: 1

Toggle decryption for SecureString parameters

/> decrypt
Decrypt is false
/> decrypt true
Decrypt is true

Get parameter history

/> history /dev/app/url
  KeyId: "alias/aws/ssm",
  Labels: [],
  LastModifiedDate: 2019-09-29 23:22:49 +0000 UTC,
  LastModifiedUser: "arn:aws:iam::318677964956:root",
  Name: "/dev/app/url",
  Policies: [],
  Tier: "Standard",
  Type: "SecureString",
  Value: "",
  Version: 1

Copy a parameter

/> cp /dev/app/url /test/app/url
/> ls -r /dev/app /test/app

Copy an entire hierarchy

/> cp -r /dev /test
/> ls -r /test

Remove parameters

/> rm /test/app/url
/> ls -r /test
/> rm -r /test
/> ls -r /test

Put new parameters

/> put
Input options. End with a blank line.
... name=/dev/app/domain
... value=""
... type=String
... description="The domain of the app in dev"

Single line version:

/> put name=/dev/app/domain value="" type=String description="The domain of the app in dev"

Put with a value containing line breaks:

/>put name=/secrets/key/private type=SecureString value="-----BEGIN RSA PRIVATE KEY-----\
... data\
... -----END RSA PRIVATE KEY-----"
Put /secrets/key/private version 1

Advanced parameters with policies

Use parameter policies to do things like expire (automatically delete) parameters at a specified time:

/> policy urlExpiration Expiration(Timestamp=2013-03-31T21:00:00.000Z)
/> policy ReminderPolicy ExpirationNotification(Before=30,Unit=days) NoChangeNotification(After=7,Unit=days)
/> put name=/dev/app/url value="" type=String policies=[urlExpiration,ReminderPolicy]

Switch AWS profile

Switches to another profile as configured in ~/.aws/config.

/> profile
/> profile project1
/> profile

Change active region

/> region eu-central-1
/> region

Operate on other regions

A few examples of working with regions.

/> put region=eu-central-1  name=/dev/app/domain value="" type=String description="The domain of the app in dev"
/> cp -r us-east-1:/dev us-west-2:/dev
/> ls -r us-west-2:/dev
/> region us-east-2
/> get us-west-2:/dev/db/username us-east-1:/dev/db/password

Read commands in batches

$ cat << EOF > commands.txt
put name=/dev/app/domain value="" type=String description="The domain of the app in dev"
rm /dev/app/domain
cp -r /dev /test
$ ssmsh -file commands.txt
$ cat commands.txt | ssmsh -file -  # Read commands from STDIN

Inline commands

$ ssmsh put name=/dev/app/domain value="" type=String description="The domain of the app in dev"

todo (maybe)

  • Flexible and improved output formats
  • Release via homebrew
  • Copy between accounts using profiles
  • Find parameter
  • Integration w/ CloudWatch Events for scheduled parameter updates
  • Export/import
  • Support globbing and/or regex
  • In memory parameter cache
  • Read parameters as local env variables




  1. Ensure you have at least go v1.17
$ go version
go version go1.17.6 darwin/arm64
  1. Ensure your $GOPATH exists and is in your $PATH
export GOPATH=$HOME/go
export PATH=$PATH:$GOROOT/bin:$GOPATH/bin
  1. Run go get
  2. Run cd $GOPATH/src/ && make to build and install the binary to $GOPATH/bin/ssmsh

Related tools

Tool Description
Chamber A tool for managing secrets
Parameter Store Manager A GUI for working with the Parameter Store
ssmple Serialize parameter store to properties


Library Use
abiosoft/ishell The interactive shell for golang
aws-sdk-go The AWS SDK for Go
mattn/go-shellwords Parsing for the shell made easy