with-ssm is a lightweight CLI tool that automatically replaces SSM parameter references in your environment variables with their actual values from AWS SSM Parameter Store before executing your commands.

Think of it as a security upgrade for your development workflow - instead of storing sensitive values directly in .env files, you reference SSM parameters that get resolved at runtime.

Why you'll love it:

🚫 No more secrets on disk - your .env files only contain SSM references
🔄 Always up-to-date - secrets are fetched fresh from SSM every time
✅ Safe to commit - your .env.with-ssm files can be safely added to version control
🎯 Drop-in replacement - works with any command that uses environment variables

Installation

npm install -g @morten-olsen/with-ssm

Quick Start

Replace secrets in your .env file with SSM references:

# .env.with-ssm
DATABASE_URL="SSM:/myapp/database/url"
API_KEY="SSM:/myapp/external/api-key"
JWT_SECRET="SSM:/myapp/auth/jwt-secret"

Run your commands through with-ssm:

with-ssm -- npm start

That's it! Your application gets the real secret values, but they never touch your filesystem.

Usage Examples

Basic Usage

# Run any command with SSM-resolved environment variables
with-ssm -- npm start
with-ssm -- node server.js
with-ssm -- docker-compose up

With Inline Environment Variables

# Mix inline SSM references with file-based ones
API_TOKEN="SSM:/external/api-token" with-ssm -- npm run deploy

Custom Files

# Use specific environment files
with-ssm --file .env.production --file .env.secrets -- npm start

AWS Configuration

# Use specific AWS profile and region
with-ssm --profile production --region us-west-2 -- npm start

Command Line Options

Option	Alias	Description	Default
`--file`	`-f`	Environment file(s) to load	`['.env', '.env.with-ssm']`
`--region`		AWS region for SSM	AWS SDK default
`--profile`		AWS profile to use	AWS SDK default
`--help`	`-h`	Show help

SSM Parameter Format

Use the SSM: prefix followed by your parameter path:

# These all work:
DATABASE_PASSWORD="SSM:/myapp/db/password"
API_KEY="SSM:/external-services/stripe/api-key"
SECRET_TOKEN="SSM:/auth/jwt-secret"

Parameters are fetched with decryption enabled, so SecureString parameters work out of the box.

File Loading Priority

with-ssm loads environment variables from files in provided order with later files override earlier ones, just like you'd expect.

Important Notes

⚠️ Application Behavior

If your application loads .env files directly (like with dotenv), it might override the SSM-resolved values. To avoid this:

Use .env.with-ssm instead of .env for SSM references
Or use environment variable substitution if your app supports it: API_KEY=${API_KEY:-SSM:/myapp/api-key}

🚀 Deployment Considerations

Don't deploy .env files with your application if they contain SSM references, and you have not added SSM resolution using with-ssm
Consider using native AWS parameter resolution in production environments
The tool requires AWS credentials configured (via AWS CLI, IAM roles, or environment variables)

AWS Setup

Make sure you have AWS credentials configured. Any of these methods work:

# AWS CLI
aws configure

# Environment variables
export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"

# IAM roles (in AWS environments)
# Automatically detected

Your AWS user/role needs ssm:GetParameters permission for the parameters you're accessing.

Examples in the Wild

Node.js Development

# .env.with-ssm
DATABASE_URL="SSM:/myapp/dev/database-url"
REDIS_URL="SSM:/myapp/dev/redis-url"
STRIPE_SECRET_KEY="SSM:/myapp/stripe/secret-key"

# Run your dev server
with-ssm -- npm run dev

Docker Compose

# Load secrets and start containers
with-ssm -- docker-compose up

CI/CD Pipeline

# Deploy with production secrets
with-ssm --profile production -- npm run deploy

How does `with-ssm` compare to...?

with-ssm's philosophy is to be a lightweight utility that enhances your existing workflow, not a heavy framework that replaces it. Here’s how it compares to other tools.

vs. `.env` files & `dotenv`

with-ssm is a security upgrade for the dotenv pattern. Instead of storing secrets in plaintext .env files, you store secure SSM: references that are safe to commit to version control. Your app gets the secrets it needs at runtime, but they never live on your disk, giving you the same simple developer experience with a major security boost.

vs. `aws-vault`

These tools are complementary and solve different problems. aws-vault securely manages your local AWS credentials, while with-ssm uses those credentials to fetch and inject application secrets. They work perfectly together—use aws-vault to handle authentication and with-ssm to handle secret resolution: aws-vault exec my-profile -- with-ssm -- npm start.

vs. `chamber`

chamber is a more powerful CLI for the full lifecycle of secret management (reading, writing, listing), while with-ssm is a lightweight utility focused only on resolving secret references from a file. Choose with-ssm for its "drop-in" simplicity and zero-config approach to enhance an existing .env workflow; choose chamber if you need a more comprehensive command-line tool for advanced SSM tasks.

vs. Cloud-Native Integrations (ECS, Lambda)

with-ssm is built for local development and CI/CD, allowing your local environment to securely mirror production. When your code is running inside an AWS environment like ECS or Lambda, you should always use the native best practice: grant the service an IAM role to fetch secrets directly via the AWS SDK.

vs. Full Secret Management Platforms (HashiCorp Vault, Doppler)

Platforms like Vault or Doppler are comprehensive, often multi-cloud solutions with their own UIs and infrastructure. with-ssm is a focused, AWS-native utility, not a platform. It's the ideal choice for teams already using AWS who want a simple, direct way to leverage SSM Parameter Store without the operational overhead of a separate service.

README.md Unescape Escape

with-ssm 🔐

What is this?