# Engage Commands

Manage Engage campaigns, email templates, and workspaces.

## Workspace Context

Engage commands require a workspace context. You can specify a workspace in two ways (in order of priority):

1. **Command option**: `--workspace <name>`
2. **Session context**: `tdx use engage_workspace <name>`



```bash
# Set workspace for the current session
tdx use engage_workspace "Marketing Team"

# Now all engage commands use this workspace
tdx engage campaigns
tdx engage campaign create --name "Newsletter" --type email

# Override workspace for a single command
tdx engage campaigns --workspace "Sales Team"
```

## Campaigns

### List Campaigns


```bash
# List all campaigns (uses workspace from session context)
tdx engage campaign list
tdx engage campaigns              # alias for "campaign list"

# List campaigns in a specific workspace
tdx engage campaign list --workspace "Marketing Team"

# Filter campaigns by pattern (glob pattern with * and ? wildcards)
tdx engage campaign list "test*"
tdx engage campaign list "*_production"

# Filter by campaign type
tdx engage campaign list --type email
tdx engage campaign list --type push

# Filter by status
tdx engage campaign list --status DRAFT
tdx engage campaign list --status ACTIVE
tdx engage campaign list --status PAUSED
tdx engage campaign list --status COMPLETED

# Combine filters
tdx engage campaign list --workspace "Marketing" --type email --status ACTIVE

# Limit results
tdx engage campaign list --limit 10
```

### Show Campaign Details


```bash
# Show campaign by name
tdx engage campaign show "My Newsletter Campaign"

# Show campaign by UUID
tdx engage campaign show "01968a3a-ae17-7ef6-9b45-f1a0af1224b4"

# Specify workspace when using name
tdx engage campaign show "My Campaign" --workspace "Marketing Team"

# Show full JSON:API response with all fields (emailContent, pushContent, etc.)
tdx engage campaign show "My Campaign" --full
```

### Create Campaign

**Note:** Workspace is required for creating campaigns. Set it via `tdx use engage_workspace` or `--workspace`.


```bash
# Create an email campaign (workspace from session)
tdx engage campaign create --name "Monthly Newsletter" --type email

# Create with explicit workspace
tdx engage campaign create --name "Monthly Newsletter" --type email \
  --workspace "Marketing Team"

# Create with description
tdx engage campaign create --name "Monthly Newsletter" --type email \
  --description "Monthly newsletter for subscribers"

# Create with segment targeting (by path)
tdx engage campaign create --name "VIP Campaign" --type email \
  --segment "My Audience/VIP Users"

# Create with email sender configuration
tdx engage campaign create --name "Monthly Newsletter" --type email \
  --email-sender-id "sender-uuid-123" \
  --json-columns "email,name,preferences"

# Create with delivery schedule
tdx engage campaign create --name "Morning Newsletter" --type email \
  --start-at "2024-01-15T09:00:00" \
  --timezone "Asia/Tokyo"

# Create a push notification campaign
tdx engage campaign create --name "Flash Sale Alert" --type push
```

### Update Campaign


```bash
# Update campaign name
tdx engage campaign update "Monthly Newsletter" --name "Weekly Newsletter"

# Update campaign description
tdx engage campaign update "Monthly Newsletter" --description "Updated description"

# Update segment targeting
tdx engage campaign update "My Campaign" \
  --segment "New Audience/Premium Users"

# Update delivery schedule
tdx engage campaign update "My Campaign" \
  --start-at "2024-02-01T10:00:00" \
  --timezone "UTC"

# Update email sender configuration
tdx engage campaign update "My Campaign" \
  --email-sender-id "new-sender-uuid"

# Specify workspace when using name
tdx engage campaign update "My Campaign" --workspace "Marketing" --name "New Name"
```

### Delete Campaign


```bash
# Delete campaign by name (prompts for confirmation)
tdx engage campaign delete "Old Campaign"

# Delete campaign by UUID
tdx engage campaign delete "01968a3a-ae17-7ef6-9b45-f1a0af1224b4"

# Skip confirmation prompt
tdx engage campaign delete "Old Campaign" --yes

# Specify workspace when using name
tdx engage campaign delete "My Campaign" --workspace "Marketing"
```

### Campaign Lifecycle Commands


```bash
# Launch a campaign (changes status from DRAFT to ACTIVE)
tdx engage campaign launch "Monthly Newsletter"
tdx engage campaign launch "01968a3a-ae17-7ef6-9b45-f1a0af1224b4"

# Pause a running campaign (changes status from ACTIVE to PAUSED)
tdx engage campaign pause "Monthly Newsletter"

# Resume a paused campaign (changes status from PAUSED to ACTIVE)
tdx engage campaign resume "Monthly Newsletter"

# Duplicate a campaign (creates a copy in DRAFT status)
tdx engage campaign duplicate "Monthly Newsletter"
```

## Email Templates

### List Templates


```bash
# List all email templates (uses workspace from session context)
tdx engage template list
tdx engage templates              # alias for "template list"

# List templates in a specific workspace
tdx engage template list --workspace "Marketing Team"

# Filter templates by pattern
tdx engage template list "welcome*"
tdx engage template list "*_newsletter"

# Limit results
tdx engage template list --limit 20
```

### Show Template Details


```bash
# Show template by name
tdx engage template show "Welcome Email"

# Show template by UUID
tdx engage template show "01968a3a-ae17-7ef6-9b45-f1a0af1224b4"

# Specify workspace when using name
tdx engage template show "Welcome Email" --workspace "Marketing"

# Show full JSON:API response with all fields (htmlTemplate, beefreeJson, etc.)
tdx engage template show "Welcome Email" --full
```

### Create Template

**Note:** Workspace is required for creating templates. Set it via `tdx use engage_workspace` or `--workspace`.


```bash
# Create an email template (workspace from session)
tdx engage template create --name "Welcome Email" \
  --subject "Welcome to our service!" \
  --html "<html><body><h1>Welcome!</h1></body></html>"

# Create with explicit workspace
tdx engage template create --name "Welcome Email" \
  --subject "Welcome to our service!" \
  --html "<html><body><h1>Welcome!</h1></body></html>" \
  --workspace "Marketing Team"

# Create with plaintext version
tdx engage template create --name "Welcome Email" \
  --subject "Welcome to our service!" \
  --html "<html><body><h1>Welcome!</h1></body></html>" \
  --plaintext "Welcome to our service!"
```

### Update Template


```bash
# Update template name
tdx engage template update "Welcome Email" --name "New Welcome Email"

# Update template subject
tdx engage template update "Welcome Email" --subject "New Subject Line"

# Update template HTML
tdx engage template update "Welcome Email" --html "<html><body><h1>Updated!</h1></body></html>"

# Update by UUID
tdx engage template update "01968a3a-ae17-7ef6-9b45-f1a0af1224b4" --name "New Name"

# Specify workspace when using name
tdx engage template update "Welcome Email" --workspace "Marketing" --name "New Name"
```

### Delete Template


```bash
# Delete template by name (prompts for confirmation)
tdx engage template delete "Old Template"

# Delete template by UUID
tdx engage template delete "01968a3a-ae17-7ef6-9b45-f1a0af1224b4"

# Skip confirmation prompt
tdx engage template delete "Old Template" --yes

# Specify workspace when using name
tdx engage template delete "My Template" --workspace "Marketing"
```

## Workspaces

### List Workspaces


```bash
# List all workspaces
tdx engage workspace list
tdx engage workspaces              # alias for "workspace list"

# Filter workspaces by pattern
tdx engage workspace list "marketing*"
tdx engage workspace list "*_production"

# Limit results
tdx engage workspace list --limit 10
```

### Show Workspace Details


```bash
# Show workspace by name
tdx engage workspace show "Marketing Team"

# Show workspace by UUID
tdx engage workspace show "01968a3a-ae17-7ef6-9b45-f1a0af1224b4"

# Show full JSON:API response with all fields (workspaceConfig, ownerUser, etc.)
tdx engage workspace show "Marketing Team" --full
```

### Create Workspace


```bash
# Create a workspace
tdx engage workspace create --name "Marketing Team"

# Create with description
tdx engage workspace create --name "Marketing Team" \
  --description "Workspace for marketing campaigns"
```

### Update Workspace


```bash
# Update workspace name
tdx engage workspace update "Marketing Team" --name "Marketing Department"

# Update workspace description
tdx engage workspace update "Marketing Team" --description "Updated description"

# Update by UUID
tdx engage workspace update "01968a3a-ae17-7ef6-9b45-f1a0af1224b4" --name "New Name"
```

### Delete Workspace


```bash
# Delete workspace by name (prompts for confirmation)
tdx engage workspace delete "Old Workspace"

# Delete workspace by UUID
tdx engage workspace delete "01968a3a-ae17-7ef6-9b45-f1a0af1224b4"

# Skip confirmation prompt
tdx engage workspace delete "Old Workspace" --yes
```

### Set Workspace Context


```bash
# Set workspace for the current session (alias for "tdx use engage_workspace")
tdx engage workspace use "Marketing Team"

# This is equivalent to:
tdx use engage_workspace "Marketing Team"
```

## Name Resolution

All Engage commands support name-based selection in addition to UUIDs:

- **By Name**: `tdx engage campaign show "My Campaign"` - searches by exact name match
- **By UUID**: `tdx engage campaign show "01968a3a-ae17-7ef6-9b45-f1a0af1224b4"` - direct ID lookup


When multiple resources share the same name across workspaces, use `--workspace` to narrow the search.

## Output Formats

All commands support standard tdx output formats:


```bash
# JSON output (default)
tdx engage campaign list

# Table format
tdx engage campaign list --format table

# TSV format for scripting
tdx engage campaign list --format tsv

# JSONL format for streaming
tdx engage campaign list --format jsonl
```

## Campaign Status Reference

| Status | Description |
|  --- | --- |
| `DRAFT` | Campaign is being prepared, not yet launched |
| `ACTIVE` | Campaign is currently running |
| `PAUSED` | Campaign is temporarily paused |
| `COMPLETED` | Campaign has finished execution |


## Campaign Types

| Type | Description |
|  --- | --- |
| `email` | Email marketing campaigns |
| `push` | Push notification campaigns |