🗝️ @sidebase/ssm-secrets

Simple 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.

✨ Features

* 🔐 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

📦 Installation

Install globally (recommended):

``bash
npm install -g @sidebase/ssm-secrets
`

Or use via npx:

`bash
npx ssm-secrets --package @sidebase/ssm-secrets
`

🚀 Usage

$3

`bash
ssm-secrets [options]
`

Run ssm-secrets --help or ssm-secrets --help for details.

$3

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

$3

List all parameters under a given SSM path.

`bash
ssm-secrets list [--format ]
`

#### 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')

$3

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.

$3

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
`

$3

Remove a parameter from SSM.

`bash
ssm-secrets delete
`

Example:

`bash
ssm-secrets delete my/service DB_PASSWORD
`

Outputs:

`
✅ Parameter deleted
`

$3

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
`

⚙️ Programmatic API

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.

🧩 Environment formats

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 storage

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.

🧠 Example workflow

`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'
``

🧾 License

MIT