aws api-gateway plugin (get-dotenv)

This guide explains the get-dotenv API Gateway plugin exported by this package:

• apiGatewayPlugin() → mounts under aws and provides:
  • aws api-gateway flush-cache
  • aws api-gateway pull-keys

If you want the programmatic API instead, see the AwsApiGatewayTools guide.

Install and import

npm i @karmaniverous/aws-api-gateway-tools
Copy

You can either:

• Use the shipped CLI (aws-api-gateway-tools), or
• Embed apiGatewayPlugin() inside your own get-dotenv host.

Using the shipped CLI

The shipped CLI is a get-dotenv CLI host composed with aws + api-gateway:

aws-api-gateway-tools aws api-gateway flush-cache
aws-api-gateway-tools aws api-gateway pull-keys --key-names '$API_KEY_A' '$API_KEY_B'
Copy

Notes:

• Relevant flags support $VAR expansion evaluated at action time against { ...process.env, ...ctx.dotenv } (ctx.dotenv wins).

Embedding the plugin in your own host

Mount the plugin under aws:

import { createCli } from '@karmaniverous/get-dotenv/cli';
import { awsPlugin } from '@karmaniverous/get-dotenv/plugins';

import { apiGatewayPlugin } from '@karmaniverous/aws-api-gateway-tools';

await createCli({
  alias: 'toolbox',
  compose: (program) => program.use(awsPlugin().use(apiGatewayPlugin())),
})();
Copy

Region sourcing:

• The plugin reads the effective region from the aws plugin’s published ctx state (ctx.plugins.aws.region) when available.
• Credentials are expected to come from the standard AWS SDK v3 provider chain (the parent aws plugin may export them into process.env depending on its configuration).

aws api-gateway flush-cache

Flushes a REST API stage cache.

Flags:

• --api-id <string>: REST API id (conflicts with --api-name)
  • Default fallback when omitted: $API_ID
• --api-name <string>: REST API name (conflicts with --api-id)
  • Default fallback when omitted: $API_NAME
• --stage-name <string>: stage name
  • Default fallback when omitted: $STAGE_NAME

All three support $VAR expansion at action time.

If api-id resolves, the plugin flushes directly; otherwise it resolves the REST API id by name and then flushes.

aws api-gateway pull-keys

Retrieves one or more API key values and writes them into a dotenv variable as a delimiter-joined string.

Flags:

• --key-names <string...> (required): space-delimited list of API key names
• --variable-name <string> (default API_KEYS): dotenv variable name to write
• --delimiter <string> (default ", "): delimiter used to join values
• --to <scope:privacy> (default env:private): destination dotenv selector
• --template-extension <string> (default template): bootstrap extension

Key behavior:

• Key names are expanded at action time (per name).
• Missing keys fail the whole command.
• Dotenv editing is format-preserving (winner-path selection) and supports template bootstrap.

Related docs

• Package overview: see the README.
• Programmatic API: see the AwsApiGatewayTools guide.