AWS Secrets Manager Tools

Tools and a get-dotenv plugin for working with AWS Secrets Manager “env-map” secrets (JSON object maps of environment variables).

This package provides:

• A tools-style wrapper that owns AWS client setup (including optional AWS X-Ray capture):
  • AwsSecretsManagerTools
• A get-dotenv plugin intended to be mounted under aws:
  • secretsPlugin() → aws secrets pull|push|delete
• A CLI embedding get-dotenv with the secrets plugin:
  • aws-secrets-manager-tools

Documentation

• Learn the programmatic API: AwsSecretsManagerTools guide
• Learn the CLI and plugin behavior: aws secrets plugin guide
• Browse the generated API reference: TypeDoc site

Install

npm i @karmaniverous/aws-secrets-manager-tools
Copy

This package is ESM-only (Node >= 20).

Quick start (programmatic)

import { AwsSecretsManagerTools } from '@karmaniverous/aws-secrets-manager-tools';

const tools = new AwsSecretsManagerTools({
  clientConfig: { region: 'us-east-1', logger: console },
  xray: 'auto',
});

const current = await tools.readEnvSecret({ secretId: 'my-app/dev' });
await tools.upsertEnvSecret({ secretId: 'my-app/dev', value: current });
Copy

When you need AWS functionality not wrapped by this package, use the fully configured AWS SDK v3 client at tools.client (see the programmatic guide for examples).

Quick start (CLI)

aws-secrets-manager-tools --env dev aws secrets pull --secret-name '$STACK_NAME'
aws-secrets-manager-tools --env dev aws secrets push --secret-name '$STACK_NAME'
aws-secrets-manager-tools --env dev aws secrets delete --secret-name '$STACK_NAME'
Copy

Notes:

• --env is a root-level (get-dotenv) option and must appear before the command path.
• Secret name expansion is evaluated at action time against { ...process.env, ...ctx.dotenv } (ctx wins).

Env-map secret format

Secrets are stored as a JSON object map of environment variables in SecretString:

{ "KEY": "value", "OPTIONAL": null }
Copy

Notes:

• Values must be strings or null.
• null is treated as undefined when decoding.

AWS X-Ray capture (optional)

X-Ray support is guarded:

• Default behavior is xray: 'auto': capture is enabled only when AWS_XRAY_DAEMON_ADDRESS is set.
• To enable capture, install the optional peer dependency:
  • aws-xray-sdk
• In auto mode, if AWS_XRAY_DAEMON_ADDRESS is set but aws-xray-sdk is not installed, construction throws.

Config defaults (getdotenv.config.*)

If you embed the plugin in your own get-dotenv host (or use the shipped CLI), you can provide safe defaults in config under plugins['aws/secrets']:

{
  "plugins": {
    "aws/secrets": {
      "secretName": "$STACK_NAME",
      "templateExtension": "template",
      "push": { "from": ["file:env:private"] },
      "pull": { "to": "env:private" },
    },
  },
}
Copy

See the secrets plugin guide for --from / --to selector details and all supported config keys.

---

Built for you with ❤️ on Bali! Find more great tools & templates on my GitHub Profile.