wraps-team/wraps/wraps-cli

@wraps.dev/cli

CLI that deploys SES, DynamoDB, Lambda, and IAM resources to your AWS account. Configures DKIM, SPF, DMARC, and event tracking automatically.

Installation

# Run directly with npx (recommended)
npx @wraps.dev/cli <command>
 
# Or install globally
npm install -g @wraps.dev/cli
wraps <command>

Quick Start

# Deploy email infrastructure
npx @wraps.dev/cli email init
 
# Check status
npx @wraps.dev/cli email status
 
# Verify domain
npx @wraps.dev/cli email verify --domain yourapp.com

Prerequisites

1. Node.js 20+
2. AWS account with credentials configured

• Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
• Or AWS CLI profile: ~/.aws/credentials
• Or IAM role (EC2, ECS, Lambda)

Email Commands

wraps email init

Deploy new email infrastructure to your AWS account.

# Interactive mode (prompts for options)
wraps email init
 
# With flags
wraps email init --provider vercel --region us-west-2 --domain myapp.com
 
# Production preset (enhanced security, multi-AZ)
wraps email init --preset production

Options:

• --provider <name> — Hosting provider (vercel, aws-lambda, generic)
• --region <region> — AWS region (default: us-east-1)
• --domain <domain> — Domain to verify for sending
• --preset <preset> — Configuration preset (default, production)

What gets deployed:

• SES Configuration (domain verification, DKIM, SPF, DMARC)
• Event Tracking (bounces, complaints, deliveries, opens, clicks)
• DynamoDB Table (email event history, 90-day TTL)
• Lambda Functions (event processing, webhook handling)
• IAM Roles (least-privilege, OIDC support for Vercel)
• CloudWatch (metrics and alarms)

All resources use the wraps-email-* namespace prefix.

wraps email status

Show current deployment status.

wraps email status

Output includes:

• Deployment state (deployed, pending, none)
• Domain verification status
• SES sending status (sandbox/production)
• Infrastructure resource summary

wraps email plan

Show the SES pricing plan per Region and what your volume costs under each.

wraps email plan                              # every deployed Region
wraps email plan --volume 100000              # price a specific monthly volume
wraps email plan --region us-east-1 --set NONE  # switch a Region to à la carte

--set accepts NONE (à la carte), ESSENTIALS, PRO, ENTERPRISE, asks for confirmation (skip with --yes), and never guesses the Region.

wraps email vdm

Show, and optionally switch, Virtual Deliverability Manager (VDM) for the account in a Region — bundled with the Essentials, Pro and Enterprise SES pricing plans.

wraps email vdm                          # read the current state
wraps email vdm --enable --yes           # turn VDM on (both sub-settings on)
wraps email vdm --disable --yes          # turn VDM off

--enable and --disable are mutually exclusive. --engagement/--no-engagement and --optimized-delivery/--no-optimized-delivery override the sub-settings when enabling; asks for confirmation unless --yes is passed.

wraps email verify

Check and guide domain DNS verification.

# Check DNS propagation
wraps email verify --domain myapp.com
 
# Auto-configure if using Route53
wraps email verify --domain myapp.com --auto

DNS Records Required:

• DKIM (3 CNAME records)
• SPF (TXT record)
• DMARC (TXT record)
• Optional: Custom MAIL FROM

wraps email upgrade

Add features to existing deployment.

# Interactive upgrade wizard
wraps email upgrade
 
# Specific upgrades
wraps email upgrade --feature tracking
wraps email upgrade --feature webhooks

wraps email domains config

Configure SES configuration set options per domain — tracking, delivery, reputation, suppression, archiving, sending, and VDM.

# Interactive menu (7 groups — select, adjust, done)
wraps email domains config
 
# For a specific domain
wraps email domains config --domain myapp.com
 
# Non-interactive flags (apply directly, no menu)
wraps email domains config --domain myapp.com --opens --clicks
wraps email domains config --domain myapp.com --tls-required --no-reputation-metrics
wraps email domains config --domain myapp.com --archive --suppress-bounce --suppress-complaint
wraps email domains config --domain myapp.com --no-sending-enabled

Flag reference:

--validation-threshold <medium|high|managed> sets Auto Validation's confidence threshold (default managed).

Notes:

• Archive uses a shared wraps-email-archive Mail Manager archive, created automatically on first use
• VDM options only appear when VDM is enabled for the account — turn it on with wraps email vdm --enable
• Auto Validation is stored inside the configuration set's suppression options — it requires suppression to already be configured (--suppress-bounce/--suppress-complaint), or wraps email domains config refuses with SUPPRESSION_OPTIONS_MISSING
• Primary domain: after changes, run wraps email upgrade to sync Pulumi state
• Additional domains: changes are saved to local metadata immediately

wraps email connect

Import existing SES infrastructure into Wraps management.

wraps email connect

Use this if you already have SES configured and want to use Wraps SDK/dashboard without redeploying.

wraps email restore

Restore infrastructure from saved metadata.

# Interactive restore
wraps email restore
 
# Skip confirmation (use with caution)
wraps email restore --force

wraps email destroy

Remove all Wraps email infrastructure.

# Interactive confirmation
wraps email destroy
 
# Skip confirmation (use with caution)
wraps email destroy --force

Warning: This removes all deployed resources. Email sending will stop working.

Configuration

State Storage

Deployment state is stored in ~/.wraps/ directory:

• One state file per AWS account + region combination
• Contains resource IDs, configuration, and metadata

Environment Variables

Common Workflows

New Project Setup

# 1. Deploy infrastructure
npx @wraps.dev/cli email init --domain myapp.com
 
# 2. Add DNS records (shown in output)
# DKIM, SPF, DMARC records for myapp.com
 
# 3. Wait for DNS propagation and verify
npx @wraps.dev/cli email verify --domain myapp.com
 
# 4. Check everything is ready
npx @wraps.dev/cli email status
 
# 5. Install SDK and start sending
npm install @wraps.dev/email

Vercel Project Setup

# 1. Deploy with Vercel provider (sets up OIDC)
npx @wraps.dev/cli email init --provider vercel --domain myapp.com
 
# 2. Copy the Role ARN from output
# Add to Vercel environment: AWS_ROLE_ARN=arn:aws:iam::...
 
# 3. In your app, use the SDK
import { WrapsEmail } from '@wraps.dev/email';
 
const email = new WrapsEmail({
  roleArn: process.env.AWS_ROLE_ARN,
});

Multi-Region Setup

# Primary region
npx @wraps.dev/cli email init --region us-east-1 --domain myapp.com
 
# Secondary region (DR)
npx @wraps.dev/cli email init --region us-west-2 --domain myapp.com

Existing SES Migration

# Import existing SES setup
npx @wraps.dev/cli email connect
 
# Add event tracking
npx @wraps.dev/cli email upgrade --feature tracking

SES Sandbox

New AWS accounts start in SES sandbox mode:

• Can only send to verified email addresses
• Limited to 200 emails/day

To exit sandbox:

1. Verify your domain: wraps email verify --domain yourapp.com
2. Request production access in AWS Console → SES → Account Dashboard
3. Provide use case, expected volume, complaint handling process

The CLI will guide you through this process.

Troubleshooting

"Credentials not found"

# Check AWS credentials
aws sts get-caller-identity
 
# Or set environment variables
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret

"Domain verification pending"

DNS propagation can take up to 72 hours. Check status:

wraps email verify --domain myapp.com

Common issues:

• CNAME records not added correctly
• TTL too high (try 300 seconds)
• DNS provider caching

"SES sandbox mode"

You need production access to send to non-verified emails:

1. Go to AWS Console → SES → Account Dashboard
2. Click "Request Production Access"
3. Fill out the form with your use case

"IAM permission denied"

Ensure your IAM user/role has these permissions:

• ses:*
• iam:CreateRole, iam:AttachRolePolicy (for OIDC setup)
• dynamodb:CreateTable, dynamodb:* (for event tracking)
• lambda:CreateFunction, lambda:* (for event processing)
• cloudwatch:PutMetricAlarm (for monitoring)

Or use the managed policy: arn:aws:iam::aws:policy/AdministratorAccess (not recommended for production).

Telemetry

The CLI collects anonymous usage data to improve the product:

• Command names and success/failure status
• System info (OS, Node version)

Never collected: AWS credentials, domains, email content, PII.

Opt out:

wraps telemetry disable
# or
export WRAPS_TELEMETRY_DISABLED=1

Resource Naming

All resources created by Wraps use consistent naming:

This makes it easy to identify and audit Wraps resources in your AWS account.

Non-Destructive

The CLI follows a non-destructive approach:

• Never modifies existing AWS resources
• Only creates new resources with wraps-* prefix
• destroy only removes resources created by Wraps
• Your existing SES configuration is never touched