# JSON Output Reference

Source: https://wraps.dev/docs/reference/json-output

Reference / 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

Copy for AI

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

Copy for AI

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

Copy for AI

### 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

Copy for AI

| 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

Copy for AI

| 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

Copy for AI

| 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

Copy for AI

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](https://wraps.dev/docs/reference/errors).

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

Copy for AI

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](https://wraps.dev/docs/reference/errors)[Environment Variables](https://wraps.dev/docs/reference/environment-variables)