@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

Node.js 20+
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 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 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

Variable	Description
`AWS_PROFILE`	AWS credentials profile to use
`AWS_REGION`	Default AWS region
`AWS_ACCESS_KEY_ID`	AWS access key (if not using profile)
`AWS_SECRET_ACCESS_KEY`	AWS secret key (if not using profile)
`WRAPS_TELEMETRY_DISABLED`	Set to `1` to disable telemetry

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:

Verify your domain: wraps email verify --domain yourapp.com
Request production access in AWS Console → SES → Account Dashboard
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:

Go to AWS Console → SES → Account Dashboard
Click "Request Production Access"
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:

Resource	Name Pattern
SES Configuration Set	`wraps-email-tracking`
DynamoDB Table	`wraps-email-events`
Lambda Functions	`wraps-email-processor`
IAM Roles	`wraps-email-*`
CloudWatch Alarms	`wraps-email-*`

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

wraps-cli