Wraps CLI Reference
Complete reference for all Wraps CLI commands.
Complete reference for all Wraps CLI commands. Deploy, manage, and monitor your AWS communication infrastructure.
Multi-Service Architecture: Wraps commands are organized by service (e.g., wraps email init, wraps cdn init, wraps sms init).
Deploy and manage AWS SES email infrastructure with event tracking, analytics, and domain management.
View Email CommandsDeploy S3 + CloudFront CDN infrastructure with browser-based image optimization.
View CDN CommandsDeploy AWS End User Messaging infrastructure for transactional and marketing SMS.
View SMS CommandsAuthenticate with the Wraps Platform for dashboard access, templates, and workflows.
View Auth CommandsSet up and diagnose your AWS credentials and permissions.
View AWS CommandsConnect your AWS infrastructure to the Wraps Platform.
View Platform CommandsThese commands read and change data in your Wraps organization: contacts, topics, segments, templates, broadcasts, events, email suppressions, workflows, approvals, API keys and the audit log. They use the Wraps API and do not deploy AWS infrastructure.
These commands send email, make a live change or delete data. Without --yes they return CONFIRMATION_REQUIRED before making any request: contacts delete, contacts import with --validate, contacts validate, segments delete, topics delete, email suppressions add, email suppressions remove, email templates publish, email templates delete, broadcasts create, broadcasts send, broadcasts resume, broadcasts cancel, workflows trigger, workflows enable, workflows retry, workflows cancel, email agent approvals approve, email agent approvals reject, api-keys revoke, and brand-kits delete. email inbound reprocess prompts when run interactively and needs --yes in a non-interactive shell or with --json (not with --dry-run).
email templates pull fetches without --yes, but it refuses to overwrite existing local files unless --yes is given. contacts export --output and audit-logs export --output refuse to overwrite an existing file in the same way. workflows disable needs no --yes. broadcasts duplicate and broadcasts update need no --yes.
List commands take --limit and --cursor. Their data includes nextCursor, which is null when there are no more results. Pass it back unchanged as --cursor and do not construct it yourself. The cursor is a page number for contacts list, events list, topics subscribers, workflows list and workflows executions. It is an offset for topics list, segments list and broadcasts recipients. It is opaque for email suppressions list, audit-logs list and email inbound list. email agent approvals list, api-keys list, brand-kits list and email metrics are not paginated.
List contacts in your organization.
Flags: --search, --email-status, --sms-status, --preferred-channel, --limit (1-100), --cursor
JSON data: contacts, total, page, pageSize, totalPages, nextCursor
Notes: The cursor is a page number. Pass nextCursor back unchanged.
Show one contact by UUID, email or externalId.
JSON data: id, externalId, email, phone, firstName, lastName, company, jobTitle, emailStatus, smsStatus, preferredChannel, properties, emailsSent, emailsOpened, emailsClicked, smsSent, smsClicked, createdAt, updatedAt, topics
Create a contact. Needs --email or --phone.
Flags: --email, --phone, --first-name, --last-name, --company, --job-title, --external-id, --email-status, --sms-status, --preferred-channel, --topic-ids, --properties (JSON object)
JSON data: id, externalId, email, phone, firstName, lastName, company, jobTitle, emailStatus, smsStatus, preferredChannel, properties, emailsSent, emailsOpened, emailsClicked, smsSent, smsClicked, createdAt, updatedAt, pendingTopics
Notes: Returns CONFLICT if the contact already exists. Search with contacts list --search first.
Change only the fields you pass.
Flags: The same field flags as contacts create
JSON data: id, externalId, email, phone, firstName, lastName, company, jobTitle, emailStatus, smsStatus, preferredChannel, properties, emailsSent, emailsOpened, emailsClicked, smsSent, smsClicked, createdAt, updatedAt, pendingTopics
Notes: At least one field flag is required.
Delete a contact.
Flags: --yes (required), --dry-run
JSON data: id, deleted, dryRun
Import a CSV or JSON file of up to 10,000 rows in one call.
Flags: --format (csv or json), --duplicate-strategy (skip or update), --topic-ids, --validate with --aws-account-id and --yes, --dry-run
JSON data: dryRun, file, format, rows, created, updated, skipped, invalid, errors, duplicates, duplicateStrategy, topicIds, sesValidation
Notes: A row that matches an existing contact by email or phone is skipped by default. update fills blank fields and merges properties, and never overwrites consent. Split a longer file into parts of at most 10,000 rows, each with the header row. --validate checks addresses with SES and AWS bills per address, so it needs --yes.
Export up to 50,000 contacts, newest first.
Flags: --format (json or csv), --output <path>, --search, --email-status, --topic-id, --yes (to overwrite --output)
JSON data: format, output, exported, total, truncated, hint, overwritten (without --output, the rows are in contacts)
Notes: The file is written only after the API answers. An existing file is not overwritten unless --yes is given. CSV in --json mode needs --output.
Check up to 100 addresses with SES Email Address Insights.
Flags: --emails <a@x.com,b@y.com> or --file <path> (one address per line), --aws-account-id (from email health), --yes, --dry-run
JSON data: requested, awsAccountId, verdicts
Notes: Needs an AWS account whose SES plan is PRO or ENTERPRISE. Reads no contacts and writes nothing. --yes is required because AWS bills per address.
List segments with live member counts. Pro plan.
Flags: --limit (1-100, default 20), --cursor (an offset)
JSON data: segments, total, limit, offset, nextCursor
Show one segment and its filter condition.
JSON data: id, name, description, condition, trackMembership, memberCount, lastComputedAt, createdAt, updatedAt
Create a segment.
Flags: --name (required), --condition (JSON, required), --description, --track-membership
JSON data: id, name, description, condition, trackMembership, memberCount, lastComputedAt, createdAt, updatedAt
Change a segment's name, description, condition or tracking.
Flags: --name, --description, --condition, --track-membership (at least one required)
JSON data: id, name, description, condition, trackMembership, memberCount, lastComputedAt, createdAt, updatedAt
Delete a segment.
Flags: --yes (required), --dry-run
JSON data: id, deleted, dryRun
Count and sample who a segment would reach. Read-only, changes nothing.
Flags: --limit
JSON data: id, count, sample
List topics with live subscriber counts. Pro plan.
Flags: --limit (1-100, default 20), --cursor (an offset)
JSON data: topics, total, limit, offset, nextCursor
Notes: The route returns every topic, so the CLI pages the list itself.
Show one topic with its audience counts.
JSON data: id, name, slug, description, public, doubleOptIn, subscriberCount, sendableCount, pendingCount, createdAt, updatedAt, createdBy
Create a topic. Needs --name.
Flags: --name (required), --description, --slug, --public (true or false), --double-opt-in (true or false)
JSON data: id, name, slug, description, public, doubleOptIn, subscriberCount, sendableCount, pendingCount, createdAt, updatedAt, createdBy
Notes: The slug is generated from the name unless you pass one. An existing slug returns CONFLICT.
Change a topic's name, slug, description, public or double opt-in.
Flags: --name, --description, --slug, --public, --double-opt-in (at least one required)
JSON data: id, name, slug, description, public, doubleOptIn, subscriberCount, sendableCount, pendingCount, createdAt, updatedAt, createdBy
Delete a topic and every subscription to it.
Flags: --yes (required), --dry-run
JSON data: id, deleted, dryRun
List a topic's subscribers.
Flags: --status (subscribed, pending or unsubscribed), --limit (1-100, default 50), --cursor (a page number, starting at 1)
JSON data: topicId, subscribers (contactId, email, status, subscribedAt, unsubscribedAt), total, page, pageSize, nextCursor
Notes: pending covers double opt-in contacts who have not confirmed yet.
List contact events, newest first.
Flags: --limit (1-100, default 50), --cursor (a page number, default 1), --event-name, --search, --contact-email, --date-from, --date-to (ISO 8601)
JSON data: events, total, page, pageSize, nextCursor
Notes: Read-only.
Show event totals and daily counts.
Flags: --days (7 or 30, default 30), --timezone
JSON data: days, totalEvents, eventsThisPeriod, activeContacts, avgEventsPerContact, dailyEvents, topEventNames
List the distinct event names.
JSON data: eventNames, count
Show one event.
JSON data: id, eventName, eventData, createdAt, contactId, contactEmail, contactFirstName, contactLastName
Save a new broadcast draft. Sends nothing.
Flags: --name, --subject, --template-id, --audience-type (all, topic or segment), --topic-id or --segment-id, --aws-account-id, --html-content, --scheduled-for (ISO time)
Notes: The output prints the broadcasts send command to run next. Change a saved draft later with broadcasts update.
Queue a broadcast. It sends immediately unless --scheduled-for is set.
Flags: --yes (required), --dry-run, --aws-account-id (from email health), --subject, --channel (email or sms), --audience-type (all, topic or segment), --topic-id, --segment-id, --template-id, --html-content, --body, --from, --from-name, --reply-to, --preview-text, --sender-id, --variable-mappings, --scheduled-for (ISO time)
JSON data: id, status, channel, createdAt, totalRecipients, payload, dryRun, warning
Notes: --dry-run validates the payload locally and makes no request.
Send a draft, from broadcasts draft or the dashboard. Broadcasts made with create are already queued.
Flags: --yes (required), --aws-account-id (from email health), --total-recipients (read it from broadcasts status)
JSON data: id, status, warning
Notes: Returns NOT_DRAFT for a broadcast that is not a draft.
Show a broadcast's status and delivery counts.
JSON data: id, name, channel, status, totalRecipients, processedRecipients, sent, delivered, failed, opened, clicked, bounced, complained, suppressed, startedAt, completedAt, createdAt
List the recipients of a broadcast.
Flags: --status, --limit (1-1000), --cursor (an offset)
JSON data: id, recipients, total, limit, offset, nextCursor
Resume a stopped broadcast.
Flags: --yes (required), --from-chunk-index
JSON data: id, resumed, fromChunkIndex
Notes: Can return RESUME_DISABLED.
Cancel a scheduled, queued or processing broadcast. It calls the existing DELETE /v1/batch/{id}.
Flags: --yes (required), --dry-run
JSON data: id, status, cancelled, dryRun
Notes: Other statuses return NOT_CANCELLABLE. There is no cancel route, so this command uses the existing delete route.
Copy any broadcast into a new draft.
JSON data: id, status, name, sourceId
Notes: The copy is named <name> (copy). It keeps the content, audience and sender, but not the schedule. No --yes needed.
Edit a draft or scheduled broadcast. Takes the same content flags as broadcasts create, plus --clear-<field>.
Flags: --clear-<field> unsets a nullable field
JSON data: id, status, name, channel, subject, audienceType, topicId, segmentId, awsAccountId, scheduledFor, updatedFields
Notes: A draft stays a draft and a scheduled broadcast stays scheduled; nothing is sent. Any other status is refused with CONFLICT. Editing a scheduled broadcast with an API key also needs the send:email scope.
List templates.
Flags: --limit (1-100), --cursor, --status (DRAFT, PUBLISHED or ARCHIVED), --channel (email or sms), --search
JSON data: templates, nextCursor
Show one template. The source is included by default.
Flags: --without-source
JSON data: id, name, slug, channel, emailType, status, subject, previewText, description, variables, source, sourceHash, compiledHtml, compiledText, lastEditedFrom, publishedAt, createdAt, updatedAt
Write every template to <slug>.tsx files in a local folder.
Flags: --out-dir (default wraps/templates), --dry-run, --yes (needed to overwrite existing files)
JSON data: outDir, dryRun, files (id, slug, path, exists, written), skipped
Notes: Refuses to overwrite existing local files unless --yes is given.
Publish a template to SES. This makes it live.
Flags: --yes (required), --aws-account-id (required when the organization has more than one AWS account)
JSON data: id, publishedAt, sesTemplateName, awsAccountId
Copy a template as a new draft.
JSON data: id, name, slug, channel, emailType, status, subject, previewText, description, variables, source, sourceHash, compiledHtml, compiledText, lastEditedFrom, publishedAt, createdAt, updatedAt
Notes: The copy is always a DRAFT.
Delete up to 100 templates, with their versions. A published SES copy is removed too, unless another template uses the same SES name.
Flags: --yes (required), --dry-run (previews the delete and makes no request)
JSON data: dryRun, route (single or bulk), deleted, notFound, count, and wouldDelete in a dry run
Notes: If any template is still used by a draft, scheduled, queued or processing broadcast, or by an enabled workflow, the whole delete is refused with CONFLICT and nothing is deleted. The error names the blocking template ids.
Aggregate sends, opens, clicks, bounces and cost for the organization.
Flags: --start-date, --end-date (ISO 8601), --timezone, --granularity (hourly, daily, weekly or monthly), --dimensions (period, domain, broadcast, template, source, account, region), --broadcast-id, --template-id, --aws-account-id (ID filters take up to 100 comma-separated values)
JSON data: object, totals, data, meta
Notes: Not paginated. Errors: INVALID_DATE, INVALID_DATE_RANGE, INVALID_GRANULARITY.
Check SES health per AWS account. Each account's id is the value for --aws-account-id.
JSON data: status, checkedAt, accounts (each with id, accountNumber, region, status, checkedAt, sandbox, productionAccessEnabled, sendingEnabled, enforcementStatus, quota, reputation)
Notes: The id is the awsAccount row id, not the 12-digit AWS account number.
List the SES suppression list.
Flags: --account <awsAccountId>, --reason (bounce or complaint), --limit, --cursor
JSON data: entries (email, reason, awsAccountId, lastUpdated), nextCursor, hasMore, deniedAccountIds, unreachableAccountIds
Notes: Without --account it covers every connected AWS account. The cursor is opaque: repeat the same --account and --reason with it. A page can be empty while hasMore is true.
Add up to 100 addresses to an AWS account's SES suppression list, so Wraps stops sending to them.
Flags: --account <awsAccountId> (required), --reason bounce|complaint (required), --file <path> (one address per line), --yes (required), --dry-run
JSON data: awsAccountId, reason, dryRun, results (email, success, alreadyPresent, error on a failure), added, alreadyPresent, failed
Notes: Adds are idempotent: an address that is already suppressed is reported as alreadyPresent. If any address fails, the command exits with code 1. Undo one address with email suppressions remove.
Remove one address from an AWS account's suppression list.
Flags: --account <awsAccountId> (required), --yes (required), --dry-run, --acknowledge-complaint
JSON data: email, awsAccountId, dryRun, wasPresent
Notes: An address suppressed for a spam complaint also needs --acknowledge-complaint. The CLI sends that flag only when you pass it. Pass it only after you have confirmed that sending to the address is safe.
List the approval queue.
Flags: --status (PENDING, APPROVED, REJECTED, SENT or FAILED)
JSON data: approvals, nextCursor
Notes: No --limit or --cursor. The whole queue is returned, and nextCursor is always null.
Approve a pending send. This executes it.
Flags: --id (required), --yes (required)
JSON data: id, agentId, organizationId, status, payload, reason, messageId, errorMessage, decidedAt, decidedBy, createdAt, updatedAt
Reject a pending send.
Flags: --id (required), --yes (required)
JSON data: id, agentId, organizationId, status, payload, reason, messageId, errorMessage, decidedAt, decidedBy, createdAt, updatedAt
List workflows, newest first.
Flags: --search (matches the name), --status (draft, enabled, paused or archived), --limit (1-100, default 50), --cursor (a page number)
JSON data: workflows, total, page, pageSize, totalPages, nextCursor
Show one workflow and its run counts.
JSON data: id, name, description, status, triggerType, version, totalExecutions, activeExecutions, completedExecutions, failedExecutions, createdBy, createdAt, updatedAt
List a workflow's runs, newest first.
Flags: --status (pending, active, paused, waiting, completed, failed or cancelled), --limit (1-100, default 50), --cursor (a page number)
JSON data: workflowId, executions (each with its contact), total, page, pageSize, totalPages, nextCursor
Show one run with its step trace.
JSON data: id, workflowId, contactId, status, currentStepId, startedAt, completedAt, createdAt, updatedAt, contact, workflowName, steps, stepEngagement
Trigger an API workflow for one contact.
Flags: --contact-id or --contact-email (one required), --data (JSON object), --yes (required), --dry-run
JSON data: workflowId, workflowName, contactId, contactEmail, data, dryRun, message
Notes: Returns WORKFLOW_REJECTED when the route rejects the run.
Create the next scheduled run.
Flags: --cron (required), --timezone, --yes (required)
JSON data: workflowId, scheduleName, cronExpression, timezone
Remove the pending scheduled run.
JSON data: workflowId, disabled
Notes: Does not need --yes.
Retry a failed execution.
Flags: --yes (required)
JSON data: executionId, message
Cancel an in-progress execution.
Flags: --yes (required)
JSON data: executionId, cancelled
List inbound emails across the connected AWS accounts, read live from the SES inbound bucket.
Flags: --account (a Wraps account id), --limit (1-100, default 20), --cursor (opaque)
Notes: Results are in S3 key order, not received time. A page can be empty while nextCursor is set; keep going until it is null. Denied or unreadable accounts make the listing incomplete.
Show one inbound email.
Flags: --account (a Wraps account id), --json
Notes: htmlTruncated is true when the HTML body was longer than 200 KB and was cut. Attachments are listed as metadata only; their contents cannot be downloaded.
List every brand kit in the organization.
Notes: Not paginated: one response. The JSON output includes a total.
Show one brand kit.
Create a brand kit. Pass --default to make it the default.
Flags: --name, --primary-color, --secondary-color, --background-color, --text-color, --font-family, --heading-font-family, --button-style, --button-radius, --company-name, --company-address, --social-links (a JSON array), --logo-url, --source-domain, --default
Notes: The first kit in the organization becomes the default. --default clears the previous default.
Change any of the create fields. At least one flag is required.
Flags: The same flags as brand-kits create
Notes: Pass null to clear a nullable field: logo, heading font, company name, company address or source domain.
Delete a brand kit.
Flags: --yes (required), --dry-run
Notes: Templates that used the kit lose the link to it. Deleting the default promotes another kit.
Make a brand kit the organization's default.
Notes: The previous default is cleared.
List the organization's API keys. Metadata only.
JSON data: apiKeys
Notes: Not paginated: there is no --cursor or --limit. Sign in with wraps auth login first. An API key cannot manage API keys, so --token and WRAPS_API_KEY are refused with SESSION_REQUIRED.
Create an API key.
Flags: --name (required), --type (live, test or restricted), --permissions (full, readonly or a comma-separated list), --expires-in-days (1-3650)
JSON data: apiKey, secretKey
Notes: The secret is shown once, in secretKey. It cannot be shown again, so store it when the command returns. --org <id> picks the organization.
Revoke an API key permanently.
Flags: --yes (required), --dry-run
JSON data: id, revoked, dryRun
Notes: Any agent using the key stops working at once.
List audit log entries, newest first.
Flags: --action, --actor (a user id), --from, --to, --limit (1-100, default 50), --cursor
JSON data: data, nextCursor, retentionDays, canExtend
Notes: The cursor is opaque. --to is exclusive: --to 2026-10-08 stops before midnight UTC on October 8. Results are limited to the plan's history window.
Export audit log entries as JSON or CSV. Business plan.
Flags: --format (json or csv), --output <path>, --action, --actor, --from, --to, --yes (to overwrite --output)
JSON data: format, output, total, truncated, bytes (without --output in JSON mode: logs, total, truncated)
Notes: Exports up to 50,000 rows. The file is written only after the API answers. An existing file is not overwritten unless --yes is given. Each export writes an audit_log.exported entry.
wraps pushPush templates and workflows to the Wraps Platform and SES
wraps newsShow latest Wraps news and updates
wraps supportOpen support channel
wraps updateUpdate the CLI to the latest version. For standalone installs, downloads the latest release from GitHub, verifies the checksum, and replaces the binary. For npm installs, shows the appropriate npm update command instead.
--account <id>Target a specific AWS account
--token <token>API token for authentication
--verboseEnable verbose output
--jsonOutput JSON (where supported)
--help, -hDisplay help information for any command
--version, -vDisplay the CLI version
--previewPreview infrastructure changes without deploying. Shows what resources would be created, updated, or deleted along with cost estimates. Available on all deployment commands (init, connect, upgrade, restore, destroy).
-y, --yesSkip confirmation prompts for non-destructive operations
-f, --forceForce destructive operations without confirmation
Display the current status of your Wraps infrastructure across all services, including deployed resources, active features, and configuration details.
npx @wraps.dev/cli statusLaunch the local Wraps console to view analytics, event tracking, and infrastructure status across all services.
npx @wraps.dev/cli console--port <port>Port to run the console on (default: 5555)
--no-openDon't automatically open browser
Remove all Wraps infrastructure from your AWS account across all services. This is a destructive operation that requires confirmation.
npx @wraps.dev/cli destroy [options]-f, --forceSkip confirmation prompt (use with caution)
--previewPreview what would be destroyed without making changes
Use service-specific destroy commands to remove individual services:
wraps email destroy - Remove email infrastructure onlywraps cdn destroy - Remove CDN infrastructure onlyManage anonymous telemetry settings. Wraps collects anonymous usage data to improve the CLI. No personal information, domains, or AWS credentials are ever collected.
npx @wraps.dev/cli telemetry # Show current statusnpx @wraps.dev/cli telemetry enable # Enable telemetrynpx @wraps.dev/cli telemetry disable # Disable telemetryYou can also disable telemetry by setting the environment variable WRAPS_TELEMETRY_DISABLED=1
Generate shell completion scripts for bash, zsh, or fish. Enables tab-completion for all Wraps commands and options.
npx @wraps.dev/cli completionAdd the output to your shell configuration file:
Bash: Add to ~/.bashrc
Zsh: Add to ~/.zshrc
Fish: Add to ~/.config/fish/config.fish
~/.wraps/Main configuration directory containing deployment metadata and Pulumi state
~/.wraps/connections/Deployment metadata files (one per AWS account/region combination)
~/.wraps/pulumi/Pulumi stack state files for infrastructure management
AWS_PROFILEAWS CLI profile to use for authentication
AWS_REGIONDefault AWS region (can be overridden with --region flag)
AWS_ACCESS_KEY_IDAWS access key (not recommended, use IAM roles or profiles instead)
AWS_SECRET_ACCESS_KEYAWS secret key (not recommended, use IAM roles or profiles instead)