AWS SSM command-line and programmatic utility
npm install @sidebase/ssm-secretsSimple AWS SSM Secrets Manager CLI
Securely manage your AWS SSM Parameters โ authenticate once via your OS keyring and easily list, get, write, or delete secrets.
* ๐ Secure local credential storage using native OS keyrings
(via keyring-node, powered by keyring-rs)
* ๐งฉ List / get / put / delete SSM parameters
* ๐ Run commands with environment variables from SSM parameters
* ๐ง Output formatting as .env or JSON
* ๐ช Works with AWS SSM Parameter Store, recursive listing included
* ๐งฐ Both CLI and programmatic API available
Install globally (recommended):
``bash`
npm install -g @sidebase/ssm-secrets
Or use via npx:
`bash`
npx ssm-secrets --package @sidebase/ssm-secrets
`bash`
ssm-secrets
Run ssm-secrets --help or ssm-secrets for details.
Store AWS credentials in your system keyring.
`bash`
ssm-secrets auth
Youโll be prompted for:
``
AWS Region: (default: eu-central-1)
AWS Access Key ID:
AWS Secret Access Key:
These are securely saved using your OSโs secret store:
* Linux: Secret Service / GNOME Keyring / KWallet
* macOS: Keychain Access
* Windows: Credential Manager
List all parameters under a given SSM path.
`bash`
ssm-secrets list
#### Examples
`bash`
ssm-secrets list my/service
ssm-secrets list my/service --format env
Output formats:
* json (default) โ structured object ({"PARAM": "value"})env
* โ shell-style lines suitable for source (PARAM='value')
Retrieve one parameter by path and name.
`bash`
ssm-secrets get
Example:
`bash`
ssm-secrets get my/service DB_PASSWORD
Outputs full JSON metadata from SSM.
Add or update a parameter in SSM.
`bash`
ssm-secrets put
Aliases:
`bash`
ssm-secrets write ...
ssm-secrets set ...
Example:
`bash`
ssm-secrets put my/service DB_PASSWORD supersecret
Displays when successful:
``
โ
Parameter stored with version 3
Remove a parameter from SSM.
`bash`
ssm-secrets delete
Example:
`bash`
ssm-secrets delete my/service DB_PASSWORD
Outputs:
``
โ
Parameter deleted
Fetches all parameters from a given SSM path, transforms them into environment
variables, and executes the provided command with that environment.
Variable names are uppercased and stripped of the path prefix.
Example: /my/app/parameter becomes PARAMETER environment variable.
`bash``
ssm-secrets exec my/app -- node server.js
If you need to pass --arguments to your command, separate them using a double dash:
`bash`
ssm-secrets exec my/app -- node server.js --inspect
Options:
* --no-overwrite
Do not overwrite existing environment variables.
* --ignore
Ignore specific parameter names (case-sensitive, without path prefix).
Example:
`bash`
ssm-secrets exec my/app --ignore FOO bar -- node server.js
You can also use the API directly in Node.js:
`js
import { listParameters, getParameter, putParameter, deleteParameter } from '@sidebase/ssm-secrets'
const secrets = await listParameters('my/service')
console.log(secrets)
await putParameter('my/service', 'DB_PASSWORD', 'supersecret')
`
All functions automatically use the credentials stored via ssm-secrets auth.
The CLI supports exporting secrets in .env-compatible format:
`bash`
ssm-secrets list my/app --format env > .env
You can then source them in a shell:
`bash`
export $(cat .env | xargs)
or directly
`bash`
source <(ssm-secrets list my/app --format env)
Credentials are stored securely in the system keyring via keyring-node:
| Platform | Backend used |
| -------- | -------------------------------------------------------------------- |
| Linux | Secret Service (works with GNOME Keyring / KWallet) |
| macOS | macOS Keychain |
| Windows | Credential Manager |
Nothing sensitive is stored in plaintext.
`bash`
ssm-secrets auth
ssm-secrets put my/app DB_USER myuser
ssm-secrets put my/app DB_PASS mypassword
ssm-secrets list my/app --format env
ssm-secrets exec my/app -- node server.js
Output:
```
DB_USER='myuser'
DB_PASS='mypassword'
MIT