# 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 |
| [`traffic`](#traffic) | Get journey traffic data (Sankey charts) |
| [`columns`](#columns) | Show journey table column mapping |
| [`activations`](#activations) | List activations for a journey |
| [`versions`](#versions) | List all versions of a journey |
| [`version create`](#version-create) | Create a new draft version of a journey |
| [`version view`](#version-view) | View a specific version of a journey |


## 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 properties (reentry, segments) at top level
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
    goal:
      name: Completed Onboarding
      segment: entry-customers
    stages:
      - name: Welcome
        # ...

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

**Key features:**

- `journeys` array is always present (even for single-version journeys)
- `goal` is defined per version entry (each version can have its own goal or none)
- Shared properties (`reentry`, `segments`) at top level apply to all versions
- `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
```

To view a specific version, use [`version view`](#version-view).

### 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 |
| `--from <date>` | Start date for period filter (YYYY-MM-DD) |
| `--to <date>` | End date for period filter (YYYY-MM-DD) |
| `--include-history` | Include raw history data in output |



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

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

# Show stats for a specific period
tdx journey stats "Onboarding Journey" --from 2026-01-01 --to 2026-01-31

# Include raw history entries (auto-switches to JSON output)
tdx journey stats "Onboarding Journey" --from 2026-01-01 --to 2026-01-31 --include-history
```

### traffic

Get journey traffic data as Sankey chart structures (conversion and activation flows).


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

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

| Option | Description |
|  --- | --- |
| `--type <type>` | Chart type: `conversion` or `activation` (default: both) |
| `--from <date>` | Start date for period filter (YYYY-MM-DD) |
| `--to <date>` | End date for period filter (YYYY-MM-DD) |
| `--limit <number>` | Maximum number of nodes |


Output is always JSON (Sankey graph data is not suited for table display).

- **Conversion**: Stage-to-stage flow showing goal, exit, and jump transitions
- **Activation**: Per-stage activation conversion rates



```bash
# Get both conversion and activation data
tdx journey traffic "Onboarding Journey"

# Get only conversion Sankey
tdx journey traffic "Onboarding Journey" --type conversion

# Get activation data for a specific period
tdx journey traffic "Onboarding Journey" --type activation --from 2026-01-01 --to 2026-01-31
```

### columns

Show the column mapping for a journey's Trino table. Maps each column name to its corresponding stage, step, and type.


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

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

Output includes the database/table name and a column list with stage index, step type, step name, direction (in/out), and category.


```bash
# Show column mapping for a journey
tdx journey columns "Onboarding Journey"

# Show columns from YAML file
tdx journey columns segments/my-audience/onboarding-journey.yml
```

### activations

List all activations configured for a journey.


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

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


```bash
# List activations for a journey
tdx journey activations "Onboarding Journey"

# List activations from YAML file
tdx journey activations segments/my-audience/onboarding-journey.yml
```

### versions

List all versions of a journey bundle.


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

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


```bash
# List all versions
tdx journey versions "Onboarding Journey"

# List versions from YAML file
tdx journey versions segments/my-audience/onboarding-journey.yml

# JSON output
tdx journey versions "Onboarding Journey" --json
```

**Output fields:**

| Field | Description |
|  --- | --- |
| `version` | Version number |
| `journey_id` | Journey ID for this version |
| `name` | Version name |
| `state` | Journey state (draft, simulation, launched) |
| `paused` | Whether this version is paused |
| `latest` | Whether this is the latest version |
| `created_at` | Creation timestamp |


### version create

Create a new draft version of a journey. The new version is cloned from the specified journey (typically the latest version).


```bash
tdx journey version create <name-or-path>
```

| Option | Description |
|  --- | --- |
| `-y, --yes` | Skip confirmation prompt |



```bash
# Create a new draft version (with confirmation prompt)
tdx journey version create "Onboarding Journey"

# Skip confirmation
tdx journey version create "Onboarding Journey" -y

# Create from YAML file reference
tdx journey version create segments/my-audience/onboarding-journey.yml
```

The new version name is auto-generated as `{bundle name} v{N+1}`.

See also: [`versions`](#versions) to list existing versions before creating a new one.

### version view

View details of a specific version of a journey. Similar to [`view`](#view) but targets a specific version number.


```bash
tdx journey version view <name-or-path> --version <number>
```

| Option | Description |
|  --- | --- |
| `--version <number>` | Version number to view (required) |



```bash
# View version 1
tdx journey version view "Onboarding Journey" --version 1

# View version 3 in JSON format
tdx journey version view "Onboarding Journey" --version 3 --json

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

**Output fields:**

| Field | Description |
|  --- | --- |
| `id` | Journey ID |
| `name` | Version name |
| `version` | Version number |
| `description` | Journey description |
| `state` | Journey state |
| `paused` | Whether paused |
| `reentry_mode` | Profile reentry behavior |
| `stages` | Number of stages |
| `goal` | Goal name (if set) |
| `latest` | Whether this is the latest version |
| `created_at` | Creation timestamp |
| `updated_at` | Last update timestamp |
| `url` | Console URL |


## 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](/ja/treasure-code/commands/parent-segment)
- [Segment Commands](/ja/treasure-code/commands/segment)