wraps-cli

name	wraps-cli
description	CLI that deploys SES, DynamoDB, Lambda, and IAM resources to your AWS account with automatic DKIM, SPF, DMARC configuration.

@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 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:

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:

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