https://github.com/karmaniverous/aws-secrets-manager-tools
Tools and get-dotenv plugin for AWS Secrets Manager env-map secrets.
https://github.com/karmaniverous/aws-secrets-manager-tools
aws aws-secrets-manager cli dotenv getdotenv secrets secrets-manager typescript xray
Last synced: 5 months ago
JSON representation
Tools and get-dotenv plugin for AWS Secrets Manager env-map secrets.
- Host: GitHub
- URL: https://github.com/karmaniverous/aws-secrets-manager-tools
- Owner: karmaniverous
- License: bsd-3-clause
- Created: 2025-12-30T07:46:16.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-08T16:58:22.000Z (5 months ago)
- Last Synced: 2026-01-13T19:42:50.632Z (5 months ago)
- Topics: aws, aws-secrets-manager, cli, dotenv, getdotenv, secrets, secrets-manager, typescript, xray
- Language: TypeScript
- Homepage: https://docs.karmanivero.us/aws-secrets-manager-tools/
- Size: 1.45 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# AWS Secrets Manager Tools
[](https://www.npmjs.com/package/@karmaniverous/aws-secrets-manager-tools)  [](https://docs.karmanivero.us/aws-secrets-manager-tools) [](./CHANGELOG.md) [](./LICENSE)
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](guides/aws-secrets-manager-tools.md)
- Learn the CLI and plugin behavior: [aws secrets plugin guide](guides/secrets-plugin.md)
- Browse the generated API reference: [TypeDoc site](https://docs.karmanivero.us/aws-secrets-manager-tools)
## Install
```bash
npm i @karmaniverous/aws-secrets-manager-tools
```
This package is ESM-only (Node >= 20).
## Quick start (programmatic)
```ts
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 });
```
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](guides/aws-secrets-manager-tools.md) for examples).
## Quick start (CLI)
```bash
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'
```
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`:
```json
{ "KEY": "value", "OPTIONAL": null }
```
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']`:
```jsonc
{
"plugins": {
"aws/secrets": {
"secretName": "$STACK_NAME",
"templateExtension": "template",
"push": { "from": ["file:env:private"] },
"pull": { "to": "env:private" },
},
},
}
```
See the [secrets plugin guide](guides/secrets-plugin.md) 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](https://github.com/karmaniverous).