Reference / JSON Output

JSON Output

Machine-readable output for every CLI command. Add --json to any command for structured output that AI agents, CI pipelines, and scripts can parse.

Envelope Format

Every JSON response follows a standardized envelope. Both success and error responses share the same top-level structure, making it easy to handle any command output programmatically.

types.ts

type JsonOutput = {  success: boolean;  command: string;        // e.g. "email.status"  data?: Record<string, unknown>;  error?: {    code: string;    message: string;    suggestion?: string;    docsUrl?: string;  };};

Field	Type	Description
`success`	boolean	Always present. `true` for successful operations, `false` for errors.
`command`	string	Dot-notation identifier for the command (e.g. `email.status`, `sms.init`).
`data`	object \| undefined	Present on success. Contains command-specific output fields.
`error`	object \| undefined	Present on failure. Contains structured error details with code, message, and optional suggestion.

Success Response Example

response.json

{  "success": true,  "command": "email.status",  "data": {    "integrationLevel": "full",    "region": "us-east-1",    "domains": ["example.com"],    "resources": {      "configSetName": "wraps-email-tracking",      "roleArn": "arn:aws:iam::123456789012:role/wraps-email-role"    },    "tracking": {      "enabled": true,      "events": ["SEND", "DELIVERY", "OPEN", "CLICK", "BOUNCE", "COMPLAINT"]    }  }}

Usage

Add the --json flag to any command. When active, all interactive prompts are suppressed and output is written as a single JSON object to stdout. Logs and spinners are sent to stderr so they do not interfere with JSON parsing.

terminal.sh

# Basic usagewraps email status --json# Pipe to jqwraps email status --json | jq .data.region# Non-interactive deploymentwraps email init --domain example.com --preset production --yes --json# CI/CD error handlingwraps email init --json || echo "Deploy failed"

Email Commands

Core Commands

Command	`command`	Key `data` fields
`email init`	`email.init`	`roleArn, configSetName, region, domain, dkimTokens`
`email status`	`email.status`	`integrationLevel, region, domains, resources, tracking`
`email connect`	`email.connect`	`roleArn, configSetName, region`
`email check`	`email.check`	`Full deliverability result (SPF, DKIM, DMARC, scores)`
`email test`	`email.test`	`messageId, from, to`
`email upgrade`	`email.upgrade`	`upgraded, region, deployment outputs`
`email destroy`	`email.destroy`	`destroyed, region`
`email config`	`email.config`	`updated, region`
`email restore`	`email.restore`	`restored, region`

Domain Commands

Command	`command`	Key `data` fields
`email domains add`	`email.domains.add`	`domain, dkimTokens`
`email domains list`	`email.domains.list`	`domains[]`
`email domains verify`	`email.domains.verify`	`domain, verified`
`email domains get-dkim`	`email.domains.get-dkim`	`domain, dkimTokens`
`email domains remove`	`email.domains.remove`	`domain, removed`

Inbound Commands

Command	`command`	Key `data` fields
`email inbound init`	`email.inbound.init`	`receivingDomain, bucketName`
`email inbound status`	`email.inbound.status`	`enabled, receivingDomain, bucketName`
`email inbound verify`	`email.inbound.verify`	`verified, receivingDomain`
`email inbound test`	`email.inbound.test`	`messageId, receivingDomain`
`email inbound destroy`	`email.inbound.destroy`	`destroyed`

Templates & Workflows

Command	`command`	Key `data` fields
`email templates init`	`email.templates.init`	`initialized, directory`
`email templates push`	`email.templates.push`	`pushed, templates[]`
`email workflows push`	`email.workflows.push`	`pushed, workflows[]`
`email workflows validate`	`email.workflows.validate`	`valid, errors[]`

SMS Commands

Command	`command`	Key `data` fields
`sms init`	`sms.init`	`roleArn, region, phoneNumber`
`sms status`	`sms.status`	`region, phoneNumber, phoneNumberType, configSetName`
`sms test`	`sms.test`	`messageId, to`
`sms destroy`	`sms.destroy`	`destroyed, region`
`sms sync`	`sms.sync`	`synced, region`
`sms upgrade`	`sms.upgrade`	`upgraded, region`
`sms verify-number`	`sms.verify-number`	`phoneNumber, verified`
`sms register`	`sms.register`	`registrationId, status`

CDN Commands

Command	`command`	Key `data` fields
`cdn init`	`cdn.init`	`bucketName, region, distributionId, distributionDomain`
`cdn status`	`cdn.status`	`bucketName, region, distributionId, distributionDomain, customDomain`
`cdn sync`	`cdn.sync`	`synced, region`
`cdn verify`	`cdn.verify`	`verified, domain`
`cdn destroy`	`cdn.destroy`	`destroyed, region`
`cdn upgrade`	`cdn.upgrade`	`upgraded, region`

Auth & Platform Commands

Command	`command`	Key `data` fields
`auth login`	`auth.login`	`authenticated, tokenType`
`auth status`	`auth.status`	`authenticated, user`
`auth logout`	`auth.logout`	`loggedOut`
`aws doctor`	`aws.doctor`	`checks[], summary, suggestions`
`platform connect`	`platform.connect`	`accountId, connectionId`
`platform update-role`	`platform.update-role`	`updated, roleArn`
`permissions`	`permissions`	`policy (IAM policy document)`

Error Handling

Errors follow the same envelope format. The process exit code is non-zero on failure, so scripts can use standard shell error handling. Error codes match the ones documented in the Error Codes reference.

error-response.json

{  "success": false,  "command": "email.init",  "error": {    "code": "NO_AWS_CREDENTIALS",    "message": "AWS credentials not found",    "suggestion": "Run: aws configure or aws sso login",    "docsUrl": "https://wraps.dev/docs/guides/aws-setup"  }}

Error Field	Description
`code`	Machine-readable error identifier (e.g. `NO_AWS_CREDENTIALS`). Matches codes in the Error Codes reference.
`message`	Human-readable error description.
`suggestion`	Optional. Actionable fix or next step the user can take.
`docsUrl`	Optional. Link to relevant documentation for further guidance.

Destructive Commands

Destructive commands (destroy) require the --force flag when used with --json. This prevents accidental deletion in automated pipelines where interactive confirmation is not available.

terminal.sh

# This will error in JSON mode without --forcewraps email destroy --json# Error: "--force flag is required in JSON mode"# Correct usagewraps email destroy --force --json

Error Codes Environment Variables