Journey Commands
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Cursorに接続
CursorにMCPサーバーをインストール
VS Codeに接続
VS CodeにMCPサーバーをインストール

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 journeys in current context
`view`	Show journey details
`pull`	Pull journey configuration to YAML
`push`	Push YAML configuration to TD
`validate`	Validate journey YAML files locally
`run`	Execute journey workflow
`pause`	Pause a running journey
`resume`	Resume a paused journey
`stats`	Show journey statistics
`traffic`	Get journey traffic data (Sankey charts)
`columns`	Show journey table column mapping
`activations`	List activations for a journey
`versions`	List all versions of a journey
`version create`	Create a new draft version of a journey
`version view`	View a specific version of a journey

Typical Workflow

# 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

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

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:

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

# 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

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

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

tdx journey list [pattern] [options]

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

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

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

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

pull

Pull journey configurations to local YAML files.

tdx journey pull [name] [options]

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

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

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

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

tdx journey validate [target]

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

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

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

# Run journey workflow
tdx journey run "Onboarding Journey"

pause

Pause a running journey and its activations.

tdx journey pause <name-or-path>

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

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

tdx journey resume <name-or-path>

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

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

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

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

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

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

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.

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

tdx journey activations <name-or-path>

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

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

tdx journey versions <name-or-path>

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

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

tdx journey version create <name-or-path>

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

# 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 to list existing versions before creating a new one.

version view

View details of a specific version of a journey. Similar to view but targets a specific version number.

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

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

# 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

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

Activation Setup

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

Activation Configuration

Journey activations can include connector_config for connector-specific settings:

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)

Overview

Key Concepts

Commands

Typical Workflow

YAML Format

Journey YAML Schema

Segment References

Segment Reference Conditions

Unified Journeys Format

Step Types

Wait Step Options

Decision Point Branches

Jump to Another Journey

Commands Reference

list

view

pull

push

validate

run

pause

resume

stats

traffic

columns

activations

versions

version create

version view

Journey States

Best Practices

Stage Design

Activation Setup

Activation Configuration

Reentry Strategy

Learn More

Was this helpful?