@pi-lab/ssm-env

Load environment variables from AWS Systems Manager Parameter Store into pi.

Install

pi install npm:@pi-lab/ssm-env

Usage

Map local environment variable names explicitly to Parameter Store parameter names:

// ~/.pi/agent/settings.json or .pi/settings.json
{
  "ssmEnv": {
    "profile": "company-dev",
    "region": "ap-southeast-1",
    "parameters": {
      "DATABASE_URL": "/example/dev/DATABASE_URL",
      "REDIS_URL": "/example/dev/REDIS_URL"
    }
  }
}

profile and region are optional. When omitted, the AWS SDK default credential and Region provider chains are used. A trusted project's ssmEnv object replaces the global ssmEnv object; project configuration is ignored when the project is untrusted.

Establish your AWS session before starting pi. For example:

aws sso login --profile company-dev
pi

The extension uses the AWS SDK v3 credential chain and existing AWS CLI/SDK profile and cached SSO session. It never invokes AWS CLI or starts a login flow.

Behavior

• Fetches parameters on every session start, in batches of at most 10
• Always requests decryption, which works for both SecureString and unencrypted parameters
• Preserves environment variables already present in the pi process
• Warns about missing parameters while loading values that exist
• Warns on configuration, authentication, network, and SSM failures without preventing session startup
• Refreshes values previously injected by this extension after session replacement or extension reload
• Never logs parameter values or writes them to disk

@pi-lab/ssm-env is independent of @pi-lab/env. Do not configure the same variable in both packages: each preserves existing variables, so plugin load order would determine which source wins.