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

### Pull Campaigns

Export campaigns from Engage to local YAML + HTML files. This is the starting point for the YAML-based campaign workflow.


```bash
# Pull all campaigns from a workspace
tdx engage campaign pull "Marketing Team"
tdx engage campaign pull --workspace "Marketing Team"

# Pull using session context
tdx use engage_workspace "Marketing Team"
tdx engage campaign pull

# Pull a specific campaign by name
tdx engage campaign pull "Marketing Team" --name "Monthly Newsletter"

# Pull only email campaigns
tdx engage campaign pull "Marketing Team" --type email

# Preview what would be written without writing files
tdx engage campaign pull "Marketing Team" --dry-run

# Skip confirmation prompt
tdx engage campaign pull "Marketing Team" --yes
```

| Option | Description |
|  --- | --- |
| `--workspace <name>` | Workspace name |
| `--name <name>` | Pull specific campaign by name |
| `--type <type>` | Filter by campaign type (`email`, `push`, `line`) |
| `--dry-run` | Show what would be written without writing |
| `-y, --yes` | Skip confirmation prompt |


Pulled files are written to `campaigns/<workspace-slug>/` under the current directory. Each campaign produces a YAML file and optionally an HTML file (if the campaign has an HTML email override).

### Push Campaigns

Push local YAML campaign files to the Engage API. Matches campaigns by name — existing campaigns are updated, new ones are created.


```bash
# Push a single campaign file
tdx engage campaign push path/to/campaign.yaml

# Push all campaign files in a directory
tdx engage campaign push path/to/campaigns/

# Push all campaigns (uses tdx.json for workspace context)
tdx engage campaign push

# Push with explicit workspace
tdx engage campaign push campaign.yaml --workspace "Marketing Team"

# Validate against API without applying changes
tdx engage campaign push campaign.yaml --dry-run

# Skip confirmation prompt
tdx engage campaign push campaign.yaml --yes
```

| Option | Description |
|  --- | --- |
| `--workspace <name>` | Workspace name (overrides tdx.json and session context) |
| `--dry-run` | Show what would be applied without applying |
| `-y, --yes` | Skip confirmation prompt |


**Workspace resolution order:** `--workspace` option > `tdx.json` (`engage_workspace` field) > session context.

### Validate Campaigns

Validate campaign YAML files locally without pushing to the API.


```bash
# Validate all campaign files in current directory
tdx engage campaign validate

# Validate a specific file
tdx engage campaign validate campaign.yaml

# Validate all campaigns in a directory
tdx engage campaign validate path/to/campaigns/

# Show all files including valid ones
tdx engage campaign validate --verbose
```

| Option | Description |
|  --- | --- |
| `--verbose` | Show all files including valid ones |


For API-level validation (resolving references), use `tdx engage campaign push --dry-run` instead.

## 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 from an HTML file
tdx engage template create --name "Welcome Email" \
  --subject "Welcome to our service!" \
  --html-file ./templates/welcome.html

# 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 template HTML from file
tdx engage template update "Welcome Email" --html-file ./templates/updated.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"
```

## LINE Sender Accounts

LINE sender accounts are the LINE Official Account credentials used to send LINE messages. Manage them before creating LINE campaigns.

### List LINE Sender Accounts


```bash
# List all LINE sender accounts
tdx engage line-sender-account list

# Filter by pattern (glob wildcards supported)
tdx engage line-sender-account list "my-brand*"

# Filter by workspace
tdx engage line-sender-account list --workspace "Marketing Team"
```

### Show LINE Sender Account Details


```bash
# Show by name
tdx engage line-sender-account show "My LINE Account"

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

# Specify workspace when using name
tdx engage line-sender-account show "My LINE Account" --workspace "Marketing Team"
```

## LINE Imagemap Images

Before creating a LINE imagemap campaign, upload the image to receive a `baseUrl`.

### Upload an Image


```bash
# Upload a JPEG image
tdx engage line-imagemap-image upload ./banner.jpg

# Upload a PNG image
tdx engage line-imagemap-image upload ./banner.png
```

**Constraints (enforced by LINE):**

| Constraint | Value |
|  --- | --- |
| Format | JPEG or PNG |
| Max file size | 10 MB |
| Min width | 1040 px |


**Example output:**


```
baseUrl: https://profile.line-scdn.net/0h...

Resized URLs:
  240px : https://profile.line-scdn.net/0h.../240
  300px : https://profile.line-scdn.net/0h.../300
  460px : https://profile.line-scdn.net/0h.../460
  700px : https://profile.line-scdn.net/0h.../700
 1040px : https://profile.line-scdn.net/0h.../1040

Use baseUrl in your campaign YAML:
  line:
    messages:
      - type: imagemap
        base_url: "https://profile.line-scdn.net/0h..."
```

Copy the `baseUrl` value into your campaign YAML `line.messages[].base_url` field.

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

## Always-On Campaigns

Always-on campaigns run continuously (no scheduling) and support a different lifecycle from regular campaigns: DRAFT → LIVE → PAUSED → FINISHED.

All always-on campaign commands require a workspace context (`--workspace` or `tdx use engage_workspace`).

### List Always-On Campaigns


```bash
# List all always-on campaigns
tdx engage always-on-campaign list --workspace "Marketing Team"
tdx engage always-on-campaigns --workspace "Marketing Team"  # alias

# Filter by pattern
tdx engage always-on-campaign list "welcome*" --workspace "Marketing Team"

# Filter by type or status
tdx engage always-on-campaign list --workspace "Marketing Team" --type email
tdx engage always-on-campaign list --workspace "Marketing Team" --status LIVE

# Combine filters
tdx engage always-on-campaign list --workspace "Marketing" --type email --status DRAFT
```

### Show Always-On Campaign Details


```bash
# Show campaign by name
tdx engage always-on-campaign show "My Campaign" --workspace "Marketing Team"

# Show campaign by UUID
tdx engage always-on-campaign show "01968a3a-ae17-7ef6-9b45-f1a0af1224b4" --workspace "Marketing Team"

# Show full JSON:API response
tdx engage always-on-campaign show "My Campaign" --workspace "Marketing Team" --full
```

### Create Always-On Campaign


```bash
# Create an email always-on campaign
tdx engage always-on-campaign create --workspace "Marketing Team" \
  --name "Welcome Flow" --type email

# Create with description and audience targeting
tdx engage always-on-campaign create --workspace "Marketing Team" \
  --name "Welcome Flow" --type email \
  --description "Automated welcome emails" \
  --segment "My Audience/New Users"

# Create a push campaign with UTM tracking
tdx engage always-on-campaign create --workspace "Marketing Team" \
  --name "Daily Digest" --type push \
  --enable-utm-tracking
```

### Update Always-On Campaign


```bash
# Update name or description
tdx engage always-on-campaign update "Welcome Flow" --workspace "Marketing Team" \
  --name "New Welcome Flow"

tdx engage always-on-campaign update "Welcome Flow" --workspace "Marketing Team" \
  --description "Updated description"

# Update audience targeting
tdx engage always-on-campaign update "Welcome Flow" --workspace "Marketing Team" \
  --segment "My Audience/Premium Users"
```

### Delete Always-On Campaign

Only DRAFT campaigns can be deleted.


```bash
# Delete with confirmation prompt
tdx engage always-on-campaign delete "Draft Campaign" --workspace "Marketing Team"

# Skip confirmation
tdx engage always-on-campaign delete "Draft Campaign" --workspace "Marketing Team" --yes
```

### Always-On Campaign Lifecycle Commands


```bash
# Launch (DRAFT → LIVE)
tdx engage always-on-campaign launch "Welcome Flow" --workspace "Marketing Team"

# Pause (LIVE → PAUSED)
tdx engage always-on-campaign pause "Welcome Flow" --workspace "Marketing Team"

# Resume (PAUSED → LIVE)
tdx engage always-on-campaign resume "Welcome Flow" --workspace "Marketing Team"

# Finish permanently (prompts for confirmation)
tdx engage always-on-campaign finish "Welcome Flow" --workspace "Marketing Team"
tdx engage always-on-campaign finish "Welcome Flow" --workspace "Marketing Team" --yes
```

### Duplicate Always-On Campaign


```bash
# Duplicate with a new name (required)
tdx engage always-on-campaign duplicate "Welcome Flow" --workspace "Marketing Team" \
  --name "Welcome Flow Copy"
```

### Always-On Campaign Status Reference

| Status | Description |
|  --- | --- |
| `DRAFT` | Campaign is being prepared, not yet launched |
| `LIVE` | Campaign is actively running |
| `PAUSED` | Campaign is temporarily paused |
| `FINISHED` | Campaign has been permanently completed |


## 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 |
| `line` | LINE messaging campaigns |


## LINE Campaign YAML Reference

LINE campaigns use a `line:` section in the campaign YAML. Two message types are supported.

### textV2 — Text Message


```yaml
type: campaign
name: My LINE Campaign
campaign_type: line

line:
  line_sender_account_id: "<sender-uuid>"   # From: tdx engage line-sender-account list
  messages:
    - type: textV2
      text: "Hello {{profile.first_name}}! Check out our latest offer."
```

### imagemap — Image with Tappable Areas

Upload the image first with `tdx engage line-imagemap-image upload`, then use the returned `baseUrl`:


```yaml
type: campaign
name: My LINE Imagemap Campaign
campaign_type: line

line:
  line_sender_account_id: "<sender-uuid>"
  messages:
    - type: imagemap
      base_url: "https://profile.line-scdn.net/0h..."   # From: tdx engage line-imagemap-image upload
      alt_text: "Tap to explore our offers"
      base_size:
        width: 1040
        height: 1040
      actions:
        # URI action — opens a URL
        - type: uri
          link_uri: "https://example.com/offer"
          label: "View Offer"
          area: { x: 0, y: 0, width: 1040, height: 1040 }
```

**Action types:**

| Type | Required fields | Description |
|  --- | --- | --- |
| `uri` | `link_uri`, `area` | Opens a URL when tapped |
| `message` | `text`, `area` | Sends `text` as a message from the user *(not yet supported)* |
| `clipboard` | `clipboard_text`, `area` | Copies `clipboard_text` to the user's clipboard *(not yet supported)* |


The `uri` action supports an optional `label` field.

**`base_size` constraints:** `width` must be `1040`. `height` can be any value, but LINE recommends a 1:1 ratio (1040×1040).

**Limits:** Up to 5 messages per `line:` section; up to 50 actions per imagemap message.

### Workflow


```bash
# 1. Find your LINE sender account
tdx engage line-sender-account list --workspace "Marketing Team"

# 2. Upload imagemap image (if using imagemap type)
tdx engage line-imagemap-image upload ./banner.jpg

# 3. Write campaign YAML (use baseUrl from step 2)

# 4. Validate locally
tdx engage campaign validate my-line-campaign.yaml

# 5. Push to API (dry-run first)
tdx engage campaign push my-line-campaign.yaml --dry-run
tdx engage campaign push my-line-campaign.yaml --yes
```

## Media (DAM)

Manage images and assets in the Engage Digital Asset Management (DAM) storage.


```bash
# List root directory
tdx engage media ls

# List a specific folder
tdx engage media ls uploads/images

# Upload an image (JPEG, PNG, GIF, SVG supported)
tdx engage media upload ./banner.jpg
tdx engage media upload ./banner.jpg --path uploads/images
tdx engage media upload ./banner.jpg --path uploads --conflict replace

# Create a directory
tdx engage media mkdir uploads/images

# Delete a file
tdx engage media rm uploads/images/banner.jpg

# Delete a directory (must be empty)
tdx engage media rmdir uploads/images
```

### Conflict strategies for `media upload`

| Strategy | Behavior |
|  --- | --- |
| `ask` (default) | Fails with HTTP 409 if the file already exists |
| `replace` | Overwrites the existing file |
| `keep` | Auto-renames to avoid conflict (e.g. `image_20240427103045.jpg`) |