# Journey Commands

Manage CDP Journey Orchestration for customer journey automation.

Premium Feature
Journey Orchestration is a premium feature. Contact your Customer Success Representative for more information.

## Overview

Journey Orchestration enables marketers to create automated customer journeys that guide customers through stages based on their behavior and attributes. Journeys differ from segments in that they track individual profile progression through defined stages over time.

### Key Concepts

- **Journey**: A timeline of stages that customers progress through toward a goal
- **Stage**: A step in the journey with entry criteria, exit criteria, and actions
- **Step**: An action or decision within a stage (wait, activation, decision point, A/B test)
- **Goal**: The desired outcome that marks journey completion
- **Reentry**: Rules for whether profiles can re-enter the journey


## Commands

| Command | Description |
|  --- | --- |
| [`list`](#list) | List journeys in current context |
| [`view`](#view) | Show journey details |
| [`pull`](#pull) | Pull journey configuration to YAML |
| [`push`](#push) | Push YAML configuration to TD |
| [`validate`](#validate) | Validate journey YAML files locally |
| [`run`](#run) | Execute journey workflow |
| [`pause`](#pause) | Pause a running journey |
| [`resume`](#resume) | Resume a paused journey |
| [`stats`](#stats) | Show journey statistics |


## Typical Workflow


```bash
# 1. Pull segments from a parent segment
tdx sg pull "My Audience"
# Creates: segments/my-audience/*.yml

# 2. Pull journeys (stored alongside segments)
tdx journey pull
# Creates: segments/my-audience/*.yml (journey files have type: journey)

# 3. Edit YAML files locally
# Edit segments/my-audience/onboarding-journey.yml

# 4. Push changes (preview first with --dry-run)
tdx journey push --dry-run   # Preview journey-only changes
tdx journey push             # Push journey-only changes
# Or push everything (segments, journeys, activations):
tdx sg push --dry-run
tdx sg push

# 5. Monitor journey statistics
tdx journey stats "Onboarding Journey"
```

## YAML Format

Journeys are stored alongside segments in the parent segment folder:


```
segments/
└── my-audience/
    ├── tdx.json                       # Parent segment context
    ├── high-value-customers.yml       # Segment
    ├── new-signups.yml                # Segment
    ├── onboarding-journey.yml         # Journey
    └── retention-campaign.yml         # Journey
```

### Journey YAML Schema


```yaml
# segments/my-audience/onboarding-journey.yml
type: journey
name: Onboarding Journey
description: New customer onboarding flow

# Goal criteria - when is the journey complete?
goal:
  name: Completed Onboarding
  segment: entry-customers  # Reference to embedded segment

# Reentry rules
reentry: no_reentry  # no_reentry | reentry_unless_goal_achieved | reentry_always

# Embedded segments - journey-local segment definitions
# These segments are created/managed with the journey
segments:
  entry-customers:
    description: New customers in the last 7 days
    rule:
      type: And
      conditions:
        - type: Value
          attribute: created_date
          operator:
            type: TimeWithinPast
            value: 7
            unit: day

  engaged-users:
    description: Users who opened welcome email
    rule:
      type: And
      conditions:
        - type: Value
          attribute: welcome_email_opened
          operator:
            type: Equal
            value: true

# Journeys array - always present (even for single version)
journeys:
  - stages:
      - name: Welcome
        description: Initial welcome and introduction

        # Entry criteria - who enters this stage?
        entry_criteria:
          name: New Users
          segment: entry-customers  # Reference to embedded segment above

        # Exit criteria - when to remove from stage (optional)
        exit_criteria:
          - name: Churned
            segment: ref:Churned Users  # ref: prefix for external segments

        # Milestone - optional tracking point
        milestone:
          name: Welcome Email Opened
          segment: engaged-users

        # Steps define the flow within this stage
        # Uses GitHub Actions-like format: type, name, with (type-specific params)
        steps:
          # Wait step - pause before action
          - type: wait
            name: Wait 1 Day
            with:
              duration: 1
              unit: day  # day/days | week/weeks

          # Activation step - send to external system
          - type: activation
            name: Send Welcome Email
            with:
              activation: "Salesforce Marketing Cloud"  # Reference by name

          # Decision point - branch based on behavior
          - type: decision_point
            name: Check Email Open
            with:
              branches:
                - name: Opened Email
                  segment: engaged-users
                  next: send_followup
                - name: Did Not Open
                  segment: ref:Did Not Open Welcome  # External segment
                  excluded: true  # This is the "else" branch
                  next: send_reminder

          # End step - exit the stage (no 'with' needed)
          - type: end
            name: Stage Complete
```

### Segment References

Journey YAML supports two types of segment references:

| Syntax | Description | Example |
|  --- | --- | --- |
| `name` | Embedded segment (defined in `segments:` section) | `segment: entry-customers` |
| `ref:Name` | External segment (existing child segment) | `segment: ref:High Value Customers` |


When pulling journeys, journey-local segments are automatically embedded, while references to external segments use the `ref:` prefix.

### Segment Reference Conditions

Within segment rules, you can include or exclude members of other segments using `type: include` or `type: exclude`:


```yaml
segments:
  # Include members of another segment
  vip_in_california:
    description: VIP customers in California
    rule:
      type: And
      conditions:
        - type: include
          segment: california_customers
        - type: Value
          attribute: tier
          operator:
            type: Equal
            value: vip

  # Exclude members of another segment
  new_non_churned:
    description: New users who haven't churned
    rule:
      type: And
      conditions:
        - type: Value
          attribute: signup_date
          operator:
            type: TimeWithinPast
            value: 30
            unit: day
        - type: exclude
          segment: churned_users
```

| Type | Description |
|  --- | --- |
| `type: include` | Include profiles that are members of the referenced segment |
| `type: exclude` | Exclude profiles that are members of the referenced segment |


### Unified Journeys Format

All journeys use a unified `journeys` array format, whether single or multi-version:


```yaml
type: journey
name: Onboarding Journey
description: New customer onboarding flow

# Shared defaults (apply to all versions unless overridden)
goal:
  name: Completed Onboarding
  segment: entry-customers
reentry: no_reentry

segments:
  entry-customers:
    description: New customers
    rule:
      # ...

# Journeys array - each entry is a version
journeys:
  - version: v1
    state: launched
    latest: true  # Active version
    stages:
      - name: Welcome
        # ...

  - version: v2
    state: draft
    # Per-version override (optional)
    goal:
      name: Completed V2
      segment: active-customers
    stages:
      - name: Welcome (New)
        # ...
```

**Key features:**

- `journeys` array is always present (even for single-version journeys)
- Shared properties (`goal`, `reentry`, `segments`) at top level serve as defaults
- Per-version overrides are optional and inherit from top-level defaults
- `version` property is optional (defaults to "v1" for single-version)
- `latest: true` marks the active version
- `state` indicates draft or launched


### Step Types

All steps use a consistent format with `type`, `name`, and type-specific parameters nested under `with`:

| Type | Description | `with` Parameters |
|  --- | --- | --- |
| `wait` | Pause execution | `duration`, `unit` (day/week) |
| `activation` | Send to external system | `activation` (name reference) |
| `decision_point` | Branch based on segment | `branches[]` |
| `ab_test` | Split traffic for testing | `variants[]`, `customized_split` |
| `merge` | Rejoin branched paths | (none - only uses `next`) |
| `jump` | Go to another journey/stage | `target.journey`, `target.stage`, `target.bundle_id` |
| `end` | Exit the stage | (none - terminates flow) |


### Wait Step Options


```yaml
# Duration-based wait
- type: wait
  name: Wait 7 Days
  with:
    duration: 7
    unit: day  # day | week

# Wait until specific date
- type: wait
  name: Wait Until Holiday
  with:
    wait_until: "2024-12-25T00:00:00Z"

# Wait until condition met (with timeout)
- type: wait
  name: Wait for Purchase
  with:
    condition:
      segment: "Made Purchase"
      timeout:
        duration: 14
        unit: day

# Wait with different paths for matched vs timeout
- type: wait
  name: Wait for Purchase
  with:
    condition:
      segment: made-purchase      # Wait until segment match
      next: follow-up             # Optional: step when matched (defaults to next step)
      timeout:
        duration: 14
        unit: day
        next: timeout-path        # Step when timeout - triggers branching
```

Condition Branching
When `timeout.next` is specified, the wait step branches into two paths:

- **Matched path**: Profiles matching the segment go to `condition.next` (or the next sequential step if omitted)
- **Timeout path**: Profiles not matching within the duration go to `timeout.next`


### Decision Point Branches


```yaml
- type: decision_point
  name: Check Engagement
  with:
    branches:
      - name: High Engagement
        segment: "Active Users"  # Child segment reference
        next: premium_path
      - name: Medium Engagement
        segment: "Moderate Users"
        next: nurture_path
      - name: Low Engagement
        excluded: true  # Catch-all for remaining
        next: reactivation_path
```

### Jump to Another Journey

Use jump steps to transfer profiles to another journey or stage:


```yaml
# Jump to another journey (by name)
- type: jump
  name: Continue in Retention Journey
  with:
    target:
      journey: "Retention Campaign"  # Journey name
      stage: "Welcome Back"          # Target stage name

# Jump to a journey in a folder
- type: jump
  name: Move to VIP Journey
  with:
    target:
      journey: "Marketing/VIP Journey"  # Folder path + journey name
      stage: "Entry"

# Jump to a local journey file (same project)
- type: jump
  name: Next Journey
  with:
    target:
      journey: retention-journey.yml  # Local .yml file reference
      stage: "Stage 1"
```

**Target Reference Formats:**

| Format | Description | Example |
|  --- | --- | --- |
| Journey name | Journey in root folder | `journey: "My Journey"` |
| Folder/Journey | Journey in subfolder | `journey: "Marketing/Campaign"` |
| `file.yml` | Local journey file | `journey: "other-journey.yml"` |


Cross-Journey Orchestration
Jump steps enable complex multi-journey workflows. Profiles exit the current journey and enter the target journey at the specified stage.

## Commands Reference

### list

List journeys in the current parent segment context.


```bash
tdx journey list [pattern] [options]
```

| Option | Description |
|  --- | --- |
| `-r, --recursive` | List recursively (tree view) |



```bash
# List all journeys in context
tdx journey list

# Filter by pattern
tdx journey list "*onboarding*"

# List recursively
tdx journey list -r
```

### view

Show journey details including stages and statistics.


```bash
tdx journey view <name-or-path> [options]
```

The `<name-or-path>` argument supports:

- Journey name: `"Onboarding Journey"`
- Path notation: `"My Audience/Onboarding Journey"`
- YAML file path: `segments/my-audience/onboarding-journey.yml`


| Option | Description |
|  --- | --- |
| `--include-stats` | Include execution statistics |



```bash
# View journey by name
tdx journey view "Onboarding Journey"

# View journey by path
tdx journey view "My Audience/Onboarding Journey"

# View journey from YAML file
tdx journey view segments/my-audience/onboarding-journey.yml

# View with statistics
tdx journey view "Onboarding Journey" --include-stats
```

### pull

Pull journey configurations to local YAML files.


```bash
tdx journey pull [name] [options]
```

| Option | Description |
|  --- | --- |
| `--dry-run` | Preview changes without writing files |
| `-y, --yes` | Skip confirmation prompt |



```bash
# Pull all journeys (requires context or tdx.json)
tdx journey pull
# Creates: segments/<parent>/*.yml (with type: journey)

# Pull specific journey
tdx journey pull "Onboarding Journey"

# Preview what would be pulled
tdx journey pull --dry-run
```

The pull command:

- Stores journeys alongside segments in the parent segment folder
- Embeds journey-local segments in the YAML file
- Uses `ref:Name` syntax for references to external segments
- Shows diff for changed files before writing


### push

Push journey YAML files to Treasure Data. This command pushes only journeys, without affecting segments or activations.


```bash
tdx journey push [target] [options]
```

The `[target]` argument can be:

- A directory path containing journey YAML files
- A specific YAML file path
- Omitted to use the current directory or context


| Option | Description |
|  --- | --- |
| `--dry-run` | Preview changes without applying |
| `-y, --yes` | Skip confirmation prompt |



```bash
# Preview journey changes
tdx journey push --dry-run

# Push journey changes
tdx journey push

# Push specific directory
tdx journey push segments/my-audience

# Push specific journey file
tdx journey push segments/my-audience/onboarding-journey.yml

# Push all files (segments, journeys, and activations)
tdx sg push
```

Journey-Only Mode
`tdx journey push` is equivalent to `tdx sg push` but only processes journey files (`type: journey`). Use it when you want to update journeys without modifying segments or activations.

### validate

Validate journey YAML files locally without pushing to Treasure Data. This catches syntax errors, missing embedded segment references, and invalid step configurations before pushing.


```bash
tdx journey validate [target]
```

| Argument | Description |
|  --- | --- |
| `target` | File or directory to validate (optional, defaults to context directory) |



```bash
# Validate all journeys in context directory
tdx journey validate

# Validate a specific journey file
tdx journey validate onboarding-journey.yml

# Validate journeys in a specific directory
tdx journey validate segments/my-audience
```

**Validations performed:**

- Missing `name` or empty `stages`
- Duplicate step names within journey
- Invalid `next` step references (must point to existing step)
- Wait step condition references to undefined embedded segments
- Decision branch references to undefined segments
- A/B test variant percentages not summing to 100%
- Invalid jump step targets
- Embedded segment rule validation


Validation also runs automatically before `tdx journey push` and `tdx sg push`, so errors are caught even if you skip this command.

### run

Execute the journey workflow to process profiles.


```bash
tdx journey run <name-or-path>
```

The `<name-or-path>` argument supports:

- Journey name: `"Onboarding Journey"`
- Path notation: `"My Audience/Onboarding Journey"`
- YAML file path: `segments/my-audience/onboarding-journey.yml`



```bash
# Run journey workflow
tdx journey run "Onboarding Journey"
```

### pause

Pause a running journey and its activations.


```bash
tdx journey pause <name-or-path>
```

The `<name-or-path>` argument supports journey name, path notation, or YAML file path.


```bash
# Pause journey by name
tdx journey pause "Onboarding Journey"

# Pause journey from YAML file
tdx journey pause segments/my-audience/onboarding-journey.yml
```

### resume

Resume a paused journey.


```bash
tdx journey resume <name-or-path>
```

The `<name-or-path>` argument supports journey name, path notation, or YAML file path.


```bash
# Resume journey by name
tdx journey resume "Onboarding Journey"

# Resume journey from YAML file
tdx journey resume segments/my-audience/onboarding-journey.yml
```

### stats

Show journey statistics including stage populations and conversion rates.


```bash
tdx journey stats <name-or-path> [options]
```

The `<name-or-path>` argument supports journey name, path notation, or YAML file path.

| Option | Description |
|  --- | --- |
| `--stage <name>` | Show stats for specific stage |
| `--period <days>` | Time period for statistics (default: 30) |



```bash
# Show overall journey stats
tdx journey stats "Onboarding Journey"

# Show specific stage stats
tdx journey stats "Onboarding Journey" --stage "Welcome"
```

**Output:**


```
Journey: Onboarding Journey
Status: Running
Last Execution: 2024-01-15 10:30:00 UTC

Stage Statistics
────────────────────────────────────────────────
  Stage        Population  Entered  Exited  Goal Rate
  Welcome           1,234    5,678   4,444     23.4%
  Engagement          890    4,444   3,554     18.2%
  Conversion          456    3,554   3,098     12.8%
  ────────────────────────────────────────────────
  Total Goal:      1,456 (25.6% of entered)
```

## Journey States

| State | Description |
|  --- | --- |
| `draft` | Journey is being edited, not yet launched |
| `simulation` | Running in simulation mode for testing |
| `launched` | Journey is live and processing profiles |
| `paused` | Journey is paused, no new profiles enter |


## Best Practices

### Stage Design

1. **Limit stages to 8 maximum** - Keep journeys focused and manageable
2. **Clear entry criteria** - Each stage should have well-defined entry conditions
3. **Use milestones for tracking** - Add milestones to measure intermediate success
4. **Plan exit criteria** - Define when profiles should leave the journey


### Activation Setup

1. **Test activations first** - Ensure activations work before adding to journey
2. **Use A/B testing** - Test different approaches before full rollout
3. **Monitor delivery rates** - Check activation success in statistics


### Activation Configuration

Journey activations can include `connector_config` for connector-specific settings:


```yaml
steps:
  - type: activation
    name: Export to S3
    with:
      activation:
        name: S3 Export
        connection: my-s3-connection
        all_columns: true
        connector_config:
          bucket: my-bucket
          path: journey-exports/users.csv
          format: csv
```

Schema Validation
When pushing journeys, tdx automatically validates `connector_config` against the connector's schema. Use `tdx connection schema <type>` to see available fields for each connector type.

### Reentry Strategy

| Strategy | Use Case |
|  --- | --- |
| `no_reentry` | One-time journeys (welcome, onboarding) |
| `reentry_unless_goal_achieved` | Repeat until goal met (conversion) |
| `reentry_always` | Recurring journeys (monthly engagement) |


## Learn More

- [Journey Orchestration Documentation](https://docs.treasuredata.com/products/customer-data-platform/journey-orchestration)
- [Parent Segment Commands](/treasure-code/commands/parent-segment)
- [Segment Commands](/treasure-code/commands/segment)