@affanshahid/awsm-env
v0.2.7
Published
A lightweight utility for syncing AWS Secrets Manager secrets to environment variables.
Maintainers
Readme
Awsm Env
A lightweight utility for syncing secrets from AWS to environment variables.
Go from an .env.example file like this:
# This directive loads the value from a secret named 'production/database-url'
# @aws-sm production/database-url
DATABASE_URL=
# Use placeholders with `$`
# @aws-sm $environment/api/secret
API_SECRET=
# Default values are preserved when no directive is present
PORT=3000to this:
DATABASE_URL="postgres://user:[email protected]/foobar"
API_SECRET="your-api-secret-from-aws"
PORT=3000Installation
Shell (Linux / macOS)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/affanshahid/awsm-env/releases/latest/download/awsm-env-installer.sh | shPowerShell (Windows)
powershell -ExecutionPolicy Bypass -c "irm https://github.com/affanshahid/awsm-env/releases/latest/download/awsm-env-installer.ps1 | iex"npm
npm install -g @affanshahid/awsm-envOr run without installing:
npx @affanshahid/awsm-envCargo
cargo install awsm-envPre-built Binaries
Pre-built archives for each supported platform are attached to every release. Download the archive for your platform, extract it, and place the awsm-env binary on your PATH:
curl -LO https://github.com/affanshahid/awsm-env/releases/latest/download/awsm-env-x86_64-unknown-linux-gnu.tar.xz
tar -xf awsm-env-x86_64-unknown-linux-gnu.tar.xz
mv awsm-env-x86_64-unknown-linux-gnu/awsm-env /usr/local/bin/Usage
Ensure AWS credentials are properly configured through:
- Environment variables (
AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY) - AWS credentials file (~/.aws/credentials)
- IAM roles for EC2/ECS instances
# Basic usage - reads from .env.example and outputs to stdout in env format
awsm-env
# Use a different example file
awsm-env path/to/my-env-spec.txt
# Write output to a file instead of stdout
awsm-env -o .env.production
# Override values
awsm-env --var API_KEY=abc123 --var DEBUG=true
# Add placeholders for secret names
awsm-env --placeholder ENVIRONMENT=production --placeholder DEBUG=true
# Export variables directly into the shell
$(awsm-env --f shell)
# Output in JSON format
awsm-env -f json
# Write to Claude Code's settings file, preserving other settings
awsm-env -f claude -o .claude/settings.local.json
# Write to Codex CLI's config file, preserving other settings
awsm-env -f codex -o .codex/config.toml
# Merge with an existing output file instead of overwriting
awsm-env -o .env -m fallback
# Don't use defaults from the spec file
awsm-env --no-defaultsSecrets
Specify AWS Secrets Manager sources using comments beginning with @aws-sm:
# @aws-sm production/database-url
DATABASE_URL=
# Parameters with @optional will be ignored if not found
# @aws-sm production/missing-parameter @optional
SOME_OPTIONAL_PARAM=Placeholders
Use placeholders to manage multiple environments:
# @aws-sm $environment/database-url
DATABASE_URL=Specify the placeholder when running awsm-env.
awsm-env -p environment=stagingThis makes it easy to switch between environments:
# Development
awsm-env -p environment=dev -o .env
# Staging
awsm-env -p environment=staging -o .env
# Production
awsm-env -p environment=production -o .envOverrides
Override or add values directly with the --var flag.
If you have an .env.example file like this:
# @aws-sm production/database-url
DATABASE_URL=
# @aws-sm production/api/secret
API_SECRET=
PORT=3000Running the following:
awsm-env .env.example \
--var API_SECRET=1234 \
--var PORT=8080 \
--var LOG_LEVEL=debugwill produce:
DATABASE_URL="<secret from aws>"
# The following values are overriden
API_SECRET="1234"
PORT="8080"
LOG_LEVEL="debug"Output
By default, awsm-env prints to stdout. Use -o to write to a file instead.
Choose from multiple output formats with the -f flag:
| Name | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| env (default) | Standard .env file format. |
| shell | Bash-compatible export statements. |
| json | JSON output of the form: {"NAME": "value"}. |
| claude | Claude Code settings file format. Updates the env key in place; other top-level settings are preserved. |
| codex | Codex CLI config.toml format. Updates the [shell_environment_policy.set] table in place, other settings are preserved. |
Defaults
By default, awsm-env preserves default values from the source file. Disable this behavior with --no-defaults to only include values from AWS or overrides.
Merge Mode
When writing to a file that already exists (via -o), awsm-env can merge the new values with the existing file's values. Control this with --merge-mode (-m):
| Mode | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| overwrite (default) | Discard the existing file and write fresh output. |
| fallback | Use the new output; for keys missing from it, fall back to the existing file's values. |
| override | Use the existing file's values for any key it defines; only add keys the existing file doesn't have. |
For example, to keep any manually-added keys in .env that aren't produced from the spec:
awsm-env -o .env -m fallbackTo refresh only keys that don't already exist in the target file (leaving hand-edited values untouched):
awsm-env -o .env -m overrideMerge mode applies to all output formats. For claude and codex, it operates on the env-variable section of the file; surrounding settings (other top-level keys) are always preserved regardless of merge mode.
Providers
The following providers are supported:
| Directive | Provider |
| -------------------------- | ------------------- |
| @aws-sm <secret_name> | AWS Secrets Manager |
| @aws-ps <parameter_name> | AWS Parameter Store |
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Prerequisites:
- Rust 1.85.1
Set up pre-commit hooks using cargo-husky:
cargo testDevelopment workflow:
# Run in development mode
cargo run
# Run test suite
cargo test
# Build release version
cargo build --release