AWS SSM Parameter Store to Environment variables

Installation

Binaries for Linux, macOS, and Windows on GitHub Releases. Download and add to PATH.

GitHub Action

Use the reusable action to install params2env in your workflows (Linux runners only):

- uses: wombelix/params2env@v0.5.0

This installs the latest released version of the CLI. To pin a specific CLI version:

- uses: wombelix/params2env@v0.5.0
  with:
    version: 0.4.0

The action version (e.g., @v0.5.0) and CLI version can differ, allowing you to use a newer action while pinning the CLI.

Go Install

Or install via Go:

go install github.com/wombelix/params2env@latest

Shell Completion

Generate shell completion scripts.

# Bash (add to ~/.bashrc)
source <(params2env completion bash)

# Zsh (add to ~/.zshrc)
source <(params2env completion zsh)

# Fish (add to ~/.config/fish/config.fish)
params2env completion fish | source

# PowerShell (add to $PROFILE)
params2env completion powershell | Out-String | Invoke-Expression

CLI

params2env reads AWS SSM Parameter Store parameters and writes them as environment variables. Also supports create, modify, and delete.

Technical details

Uses AWS Go SDK. Minimal dependencies, prefers Go standard library (slog, testing) where possible.

Config via YAML file (~/.params2env.yaml or .params2env.yaml) or CLI args. CLI args override config. Local config takes precedence over home directory.

Usage

Global flags:

Flag	Description
`--loglevel`	`debug`, `info`, `warn`, `error`, `fatal`, `panic` (default: `info`)
`--version`	Print version
`--help`	Print help

Subcommand: read

Flag	Description
`--region`	AWS region (or use `AWS_REGION`/`AWS_PROFILE` env vars)
`--path`	Parameter path (required)
`--role`	IAM role ARN to assume
`--file`	Output file (default: stdout)
`--format`	Output format: `env` or `github-env` (default: `env`)
`--upper`	Uppercase env var names (default: `true`)
`--env-prefix`	Prefix for env var names
`--env`	Custom env var name (overrides auto-generated name)

Environment variable naming:

By default, the env var name is the last segment of the parameter path. With --upper (enabled by default), it gets uppercased.

Parameter Path	`--env-prefix`	`--upper`	Result
`/app/db_password`	-	true	`DB_PASSWORD`
`/app/db_password`	`APP`	true	`APP_DB_PASSWORD`
`/app/db_password`	-	false	`db_password`

Use --env to set a fully custom name when auto-generation doesn't fit.

Output formats:

Format	Output	Use case
`env` (default)	`export KEY="value"`	Shell sourcing
`github-env`	`KEY=value`	GitHub Actions with automatic masking

GitHub Actions usage:

The github-env format outputs masking commands (::add-mask::value) to stdout and appends KEY=value to the $GITHUB_ENV file.

# GitHub Actions workflow
- name: Load secrets
  run: |
    params2env read --path "/app/db-password" --format github-env
    # Automatically writes to $GITHUB_ENV and masks the value

# Manual file specification
params2env read --path "/app/secret" --format github-env --file secrets.env

Example:

params2env read --region "eu-central-1" --path "/my/secret" \
  --role "arn:aws:iam::111122223333:role/my-role" \
  --file "~/.my-secret" --upper "false" \
  --env-prefix "my_" --env "secret"

# GitHub Actions format
params2env read --path "/app/db-password" --format github-env

# Traditional shell format
params2env read --path "/app/config" --format env

Result in ~/.my-secret:

export my_secret="<secret-value>"

To set env vars in your shell:

# Using eval
eval $(params2env read --path "/my/secret")

# Using source
source <(params2env read --path "/my/secret")

Subcommand: create

Flag	Description
`--region`	AWS region (or use `AWS_REGION` env var)
`--replica`	Replica region
`--path`	Parameter path (required)
`--description`	Parameter description
`--value`	Parameter value (optional, see below)
`--type`	`String` or `SecureString` (default: `String`)
`--kms`	KMS Key ID for SecureString (e.g., `alias/aws/ssm` or `alias/myapp-key`)
`--role`	IAM role ARN to assume
`--overwrite`	Overwrite existing (default: `false`)

Value input methods (in order of precedence):

--value flag
Piped stdin (e.g., echo "secret" | params2env create ...)
Interactive prompt (SecureString: hidden, String: visible)

Example:

params2env create --region "eu-central-1" --replica "eu-west-1" \
  --path "/my/secret" \
  --description "Secret stored as SecureString" \
  --value "S3cr3t" --type "SecureString" \
  --kms "alias/myapp-key" \
  --role "arn:aws:iam::111122223333:role/my-role"

# Pipe value to avoid shell history
echo "S3cr3t" | params2env create --path "/my/secret" \
  --type "SecureString" --kms "alias/myapp-key"

# AWS managed key
params2env create --path "/my/secret" --type "SecureString" --kms "alias/aws/ssm"

# Interactive (prompts for value, hidden for SecureString)
params2env create --path "/my/secret" --type "SecureString" --kms "alias/myapp-key"

Subcommand: modify

Flag	Description
`--region`	AWS region (or use `AWS_REGION` env var)
`--replica`	Replica region
`--path`	Parameter path (required)
`--description`	Parameter description
`--value`	New value (optional, see below)
`--role`	IAM role ARN to assume

Value input methods (in order of precedence):

--value flag
Piped stdin (e.g., echo "newvalue" | params2env modify ...)
Interactive prompt

Example:

params2env modify --region "eu-central-1" --replica "eu-west-1" \
  --path "/my/secret" \
  --description "Secret stored as SecureString" \
  --value "S3cr3t" \
  --role "arn:aws:iam::111122223333:role/my-role"

# Pipe value
echo "NewValue" | params2env modify --path "/my/secret"

# Interactive
params2env modify --path "/my/secret"

Subcommand: delete

Flag	Description
`--region`	AWS region (or use `AWS_REGION` env var)
`--replica`	Replica region to delete from
`--path`	Parameter path (required)
`--role`	IAM role ARN to assume

Example:

params2env delete --region "eu-central-1" --replica "eu-west-1" \
  --path "/my/secret" \
  --role "arn:aws:iam::111122223333:role/my-role"

YAML configuration file reference

Config file locations (local overrides global): Global: ~/.params2env.yaml. Local: .params2env.yaml.

region: <aws region>
replica: <replica region>
prefix: <search path prefix>
file: <output file>
format: <output format: env or github-env>
upper: <uppercase env names, default true>
env_prefix: <env var prefix>
role: <iam role to assume>
kms: <kms key for SecureString>
params:
  - name: <param path>
    env: <custom env var name>
    region: <region override>
    output: <output format override>

Config fields by command

Config Field	`create`	`modify`	`delete`	`read`
`region`	✓	✓	✓	✓
`replica`	✓	✓	✓	-
`role`	✓	✓	✓	✓
`kms`	✓	-	-	-
`format`	-	-	-	✓
`env_prefix`	-	-	-	✓
`file`	-	-	-	✓
`upper`	-	-	-	✓
`params`	-	-	-	✓

kms is only needed for create with SecureString. Modify and delete don't change encryption.

replica keeps parameters in sync across regions during write operations.

read fetches from one region only. Use per-param region override for multi-region reads.

Example: Simplify commands with config

Without config, creating a SecureString requires many flags:

params2env create --path /app/secret --value "s3cr3t" --type SecureString \
  --region eu-central-1 --replica eu-west-1 \
  --role arn:aws:iam::123456789012:role/my-role --kms alias/my-key

With this config file:

region: eu-central-1
replica: eu-west-1
role: arn:aws:iam::123456789012:role/my-role
kms: alias/my-key

Commands simplify to:

params2env create --path /app/secret --value "s3cr3t" --type SecureString
params2env create --path /app/secret --type SecureString  # prompts for value
params2env modify --path /app/secret --value "new-value"
params2env modify --path /app/secret                      # prompts for value
params2env delete --path /app/secret

Example: Batch read with config

region: eu-central-1
role: arn:aws:iam::123456789012:role/my-role
env_prefix: APP
format: github-env
upper: true
params:
  - name: /app/db_password              # → APP_DB_PASSWORD (auto)
  - name: /app/api_token                # → APP_API_TOKEN (auto)
  - name: /legacy/weird-name.v2
    env: LEGACY_KEY                     # → LEGACY_KEY (override)
  - name: /other/endpoint
    region: us-east-1                   # → APP_ENDPOINT (different region)

params2env read                       # Read all from config (github-env format)
params2env read --file ~/.env         # Write to file (github-env format)
params2env read --format env          # Override to traditional shell format
params2env read --path /custom/param  # Single param (ignores params list)

Build and Test

Makefile

make build   # Build binary
make tests   # Run tests with coverage
make clean   # Remove binary and coverage files

Integration Tests

tests/integration-tests.sh tests against real AWS.

export AWS_ACCOUNT_ID="123456789012"
export PRIMARY_REGION="eu-central-1"
export SECONDARY_REGION="eu-west-1"
export AWS_IAM_PRINCIPAL="arn:aws:iam::123456789012:role/YourRole"

# Optional: use existing KMS keys instead of creating new ones
export PRIMARY_KEY_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export REPLICA_KEY_ID="yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"

./tests/integration-tests.sh

Creates IAM roles/policies, tests all param types, cleans up after. KMS tests cost $1/month per key, the script asks before creating. Set PRIMARY_KEY_ID and REPLICA_KEY_ID to use existing keys.

Source

The primary location is: github.com/wombelix/params2env

Mirrors are available on Codeberg and Gitlab.

Contribute

Pick the platform you prefer and are most comfortable with. Provide feedback, open an issue or create a pull / merge request.

License

Unless otherwise stated: Apache 2.0

All files contain license information either as a header comment or a corresponding .license file.

REUSE from the FSFE is implemented to verify license and copyright compliance.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
LICENSES		LICENSES
cmd		cmd
internal		internal
tests		tests
.build.yaml		.build.yaml
.cz.toml		.cz.toml
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
.markdownlint.yaml		.markdownlint.yaml
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CHANGELOG.md.license		CHANGELOG.md.license
LICENSE		LICENSE
README.md		README.md
Taskfile.yml		Taskfile.yml
action.yml		action.yml
go.mod		go.mod
go.sum		go.sum
go.sum.license		go.sum.license
main.go		main.go

Navigation Menu

Repository files navigation

AWS SSM Parameter Store to Environment variables

Table of Contents

Installation

GitHub Action

Go Install

Shell Completion

CLI

Technical details

Usage

Subcommand: read

Subcommand: create

Subcommand: modify

Subcommand: delete

YAML configuration file reference

Config fields by command

Example: Simplify commands with config

Example: Batch read with config

Build and Test

Makefile

Integration Tests

Source

Contribute

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

AWS SSM Parameter Store to Environment variables

Table of Contents

Installation

GitHub Action

Go Install

Shell Completion

CLI

Technical details

Usage

Subcommand: read

Subcommand: create

Subcommand: modify

Subcommand: delete

YAML configuration file reference

Config fields by command

Example: Simplify commands with config

Example: Batch read with config

Build and Test

Makefile

Integration Tests

Source

Contribute

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages