# Parent Segment Commands

Manage CDP parent segments (audiences) with YAML-based configuration files.


```bash
tdx parent-segment <command>   # Full command
tdx ps <command>               # Shorthand alias
```

| Command | Description |
|  --- | --- |
| [`list`](#list) | List all parent segments |
| [`use`](#use) | Set parent segment context for subsequent commands |
| [`pull`](#pull) | Download configuration from CDP API to YAML file |
| [`push`](#push) | Upload YAML configuration to CDP API (create/update) |
| [`validate`](#validate) | Query database tables to check schema and join statistics |
| [`preview`](#preview) | Query database tables for sample data |
| [`run`](#run) | Push changes (if any) and trigger workflow |
| [`fields`](#fields) | List available fields for segmentation |
| [`view`](#view) | Show parent segment details (or open in browser with `-w`) |
| [`desc`](#desc) | Show parent segment schema (column types) |
| [`sql`](#sql) | Get SQL query for parent segment |
| [`show`](#show) | Execute SQL query and show results |
| [`rt`](#rt-2-0-commands) | RT 2.0 configuration management (`list`, `validate`) |
| [`pz`](#personalization-commands) | Personalization service management (`list`, `init`) |


## Typical Usage


```bash
# 1. Pull config (auto-sets context for subsequent commands)
tdx ps pull "Customer 360"
# Creates: parent_segments/customer-360.yml

# 2. Edit YAML file locally (add attributes, behaviors, etc.)
# Open parent_segments/customer-360.yml in your text editor

# 3. Validate configuration (name omitted - uses context)
tdx ps validate

# 4. Preview sample data
tdx ps preview --master
tdx ps preview --attribute "User Profile"
tdx ps preview --behavior "Purchases"

# 5. Push changes and run workflow
tdx ps run

# Or just push to trigger scheduled run
tdx ps push
```

Behavior Statistics Time Range
The default interval `--interval -1d` only counts behavior events from the last 24 hours. For behaviors with lower activity or weekly/monthly patterns, use a longer interval:


```bash
tdx ps validate --interval -7d    # Last 7 days
tdx ps validate --interval -30d   # Last 30 days
```

## How It Works

A **parent segment** defines the master customer table and its related data sources (attributes and behaviors) for CDP audience building. The YAML configuration specifies:

- **Master table**: The primary customer/user table with unique identifiers
- **Attributes**: Dimension tables joined to enrich customer profiles
- **Behaviors**: Event/transaction tables for behavioral segmentation


The `tdx parent-segment` commands help you manage these configurations as local YAML files. You can `pull` existing configurations from Treasure AI, edit them locally, `validate` against source tables, `preview` sample data, and `push` changes back. The `run` command triggers the workflow execution.

When the workflow runs, it creates an output database (`cdp_audience_xxx`) containing the enriched `customers` table and behavior tables that child segments query for audience creation. Once created, you can explore this data using `tdx ps desc` (schema), `tdx ps sql` (query), and `tdx ps show` (sample data).


```mermaid
flowchart TB
    subgraph LOCAL["Local"]
        YAML["parent_segments/*.yml"]
    end

    subgraph TD["Treasure AI"]
        API["CDP API"]
        DB[("Source Tables")]
        WF["Treasure Workflow"]
        subgraph CDP["cdp_audience_xxx database"]
            TABLES[("customers<br/>behavior tables")]
        end
        CHILD["Child Segments"]
    end

    YAML <-->|"pull / push"| API
    YAML -.->|"validate / preview"| DB
    API -->|"run / scheduled"| WF
    DB -->|"input"| WF
    WF -->|"creates"| TABLES
    CHILD -.->|"queries"| TABLES
```

## Folder Structure

Parent segment YAML files are stored in the `parent_segments/` directory by convention:


```
parent_segments/
├── customer-360.yml
├── demo-audience.yml
└── sales-leads.yml
```

All commands accept `<name>` without the `.yml` suffix:

- `tdx ps validate customer-360` looks for `parent_segments/customer-360.yml`
- Explicit paths still work: `tdx ps validate ./other/path/file.yml`


## Commands

### list

List all parent segments.


```bash
tdx ps list [pattern]
```


```bash
# List all parent segments (alphabetically sorted)
tdx ps list

# Filter by wildcard pattern
tdx ps list "Customer*"
tdx ps list "*Demo"

# Case-insensitive matching
tdx ps list "*test*"
```

**Example output:**


```
✔ Found 3 parent segments
👥 customer-360 (2.5M)
👥 customer-demo (50K)
👥 sales-leads (12.5K)
```

### use

Set or show parent segment context. When a name is provided, sets the context. Without arguments, shows the current context.


```bash
tdx ps use [name]
```

This is equivalent to `tdx use parent_segment [name]`.


```bash
# Show current context
tdx ps use

# Set context to a parent segment
tdx ps use "Customer 360"

# Now these commands work without specifying the name
tdx ps pull
tdx ps push
tdx ps fields
tdx ps view
tdx ps desc
tdx ps sql
tdx ps show

# Clear context
tdx use --clear parent_segment
```

**Example output (show context):**


```
Session Context
  parent_segment: Customer 360
```

**Example output (set context):**


```
✔ Context set: parent_segment = Customer 360
```

### pull

Pull a parent segment configuration from Treasure AI to a local YAML file.


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

| Option | Description |
|  --- | --- |
| `-o, --output <file>` | Output file path (default: `parent_segments/<normalized-name>.yml`) |
| `-y, --yes` | Skip confirmation prompt |


The `name` argument is optional if you have set a parent segment context with `tdx ps use`.

Pull automatically sets the context to the pulled parent segment.


```bash
# Pull to default location (normalizes name to lowercase with hyphens)
tdx ps pull "Customer 360"
# Creates: parent_segments/customer-360.yml

# Pull to specific file
tdx ps pull "Customer 360" -o custom-name.yml

# Skip confirmation
tdx ps pull "Customer 360" -y

# With context set (tdx ps use "Customer 360")
tdx ps pull
```

### push

Push a local YAML configuration to Treasure AI (creates new or updates existing).


```bash
tdx ps push [name] [options]
```

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


The `name` argument is optional if you have set a parent segment context with `tdx ps use`.


```bash
# Push configuration (looks for parent_segments/customer360.yml)
tdx ps push customer360

# Explicit path
tdx ps push ./configs/customer360.yml

# Skip confirmation
tdx ps push customer360 -y

# With context set (tdx ps use "customer360")
tdx ps push
```

**Example diff output:**


```
Changes to apply to 'Customer 360':
────────────────────────────────────────────────────────────
  6   6     - name: User Profile
  7   7       columns:
  8     -       - column: age
  9     -         type: number
      8 +       - column: age
      9 +         label: "Customer Age"
     10 +         type: number
     11 +       - column: income
     12 +         label: "Annual Income"
     13 +         type: number
────────────────────────────────────────────────────────────
Apply changes to 'Customer 360'? [y/N]
```

### validate

Validate a parent segment YAML configuration by executing schema queries and showing join statistics.


```bash
tdx ps validate <name> [options]
```

| Option | Description |
|  --- | --- |
| `--master` | Validate only master table |
| `--attribute [name]` | Validate attributes (optionally filter by name) |
| `--behavior [name]` | Validate behaviors (optionally filter by name) |
| `--enriched` | Validate enriched master schema |
| `--interval <range>` | Time range for behavior stats (default: `-1d`) |



```bash
# Validate all components
tdx ps validate customer360

# Validate only master table
tdx ps validate customer360 --master

# Validate only attributes
tdx ps validate customer360 --attribute

# Validate a specific attribute
tdx ps validate customer360 --attribute "User Profile"

# Validate only behaviors
tdx ps validate customer360 --behavior

# Validate a specific behavior
tdx ps validate customer360 --behavior "Purchases"

# Validate enriched master schema
tdx ps validate customer360 --enriched

# Custom time range for behavior stats
tdx ps validate customer360 --interval -7d
```

**Example output:**


```
Validate: Customer 360

Master Table
  cdp_db.customers (2.5M rows)

Attributes
  User Profile — Coverage: 95.2% (2.38M rows)
  Contact Info — Coverage: 78.5% (1.96M rows)

Behaviors (-1d)
  Purchases — 1.2M customers (48.0%), 8.5M events

────────────────────────────────────────────────────────────
Configuration is valid

To view sample data:
  tdx ps preview customer360 --attribute "User Profile"
  tdx ps preview customer360 --behavior "Purchases"
```

### preview

Show sample data from a parent segment YAML configuration.


```bash
tdx ps preview <name> [options]
```

| Option | Description |
|  --- | --- |
| `--master` | Show master table sample |
| `--attribute <name>` | Show attribute sample data |
| `--behavior <name>` | Show behavior sample data |
| `--enriched` | Show enriched master sample |
| `--interval <range>` | Time range for behavior queries (default: `-1d`) |


One of `--master`, `--attribute`, `--behavior`, or `--enriched` is required.


```bash
# Show master table sample
tdx ps preview customer360 --master

# Show attribute sample data
tdx ps preview customer360 --attribute "User Profile"

# Show behavior sample data
tdx ps preview customer360 --behavior "Purchases"

# Show enriched master sample
tdx ps preview customer360 --enriched

# Custom time range
tdx ps preview customer360 --behavior "Page Views" --interval -7d
```

**Example output:**


```
Attribute: User Profile — Coverage: 95.2% (2.38M rows)
┌─────────────┬─────┬────────┬────────┐
│ customer_id │ age │ gender │ income │
├─────────────┼─────┼────────┼────────┤
│ C001        │  35 │ M      │  75000 │
│ C002        │  28 │ F      │  62000 │
│ C003        │  42 │ M      │  95000 │
└─────────────┴─────┴────────┴────────┘
```

### run

Run the parent segment workflow to (re)generate the audience.


```bash
tdx ps run <name> [options]
```

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


If a local YAML file exists for the segment, it will be pushed first before running the workflow.


```bash
# Run workflow (pushes YAML if exists locally)
tdx ps run customer360

# Skip confirmation
tdx ps run customer360 -y
```

**Example output:**


```
✔ Workflow started
  Audience ID: 12345
  Status: running
  Session: 306281053
  Attempt: 987654321
  https://console.us01.treasuredata.com/app/workflows/44073028/sessions/306281053/attempt/987654321

To cancel: tdx wf attempt 987654321 kill
```

### fields

List available fields for segmentation from a parent segment.


```bash
tdx ps fields [name]
```

The `name` argument is optional if you have set a parent segment context with `tdx ps use`.


```bash
# List all available fields
tdx ps fields "Customer 360"

# JSON output
tdx ps fields "Customer 360" --json

# With context set (tdx ps use "Customer 360")
tdx ps fields
```

**Example output:**


```
Fields for Customer 360
────────────────────────────────────────────────────────────
  Name                  Type      Source
  customer_id           string    master
  email                 string    master
  age                   number    User Profile (attribute)
  gender                string    User Profile (attribute)
  purchase_amount       number    Purchases (behavior)
  purchased_at          timestamp Purchases (behavior)
```

### view

Show parent segment details or open in web browser.


```bash
tdx ps view [name] [options]
```

| Option | Description |
|  --- | --- |
| `-w, --web` | Open parent segment in web browser |


The `name` argument is optional if you have set a parent segment context with `tdx ps use`.


```bash
# Show segment details
tdx ps view "Customer 360"

# Open in web browser
tdx ps view "Customer 360" -w

# JSON output for programmatic access
tdx ps view "Customer 360" --json

# With context set (tdx ps use "Customer 360")
tdx ps view
tdx ps view -w
```

**Example output:**


```
┌──────────────────┬────────────────────────────────────────┐
│ id               │ 12345                                  │
│ name             │ Customer 360                           │
│ description      │ Complete customer view                 │
│ populationCount  │ 2500000                                │
│ audienceDatabaseName │ cdp_audience_12345                 │
│ createdAt        │ 2024-01-15T10:30:00Z                   │
│ updatedAt        │ 2024-03-20T14:45:00Z                   │
└──────────────────┴────────────────────────────────────────┘
```

**Example output (with `-w`):**


```
✔ Opening https://console-next.us01.treasuredata.com/app/dw/parentSegments/12345
```

### desc

Show parent segment output database schema (column types) for the `customers` table and behavior tables.


```bash
tdx ps desc [name] [options]
```

| Option | Description |
|  --- | --- |
| `-o, --output <file>` | Output file path |


The `name` argument is optional if you have set a parent segment context with `tdx ps use`.


```bash
# Show all tables to stdout
tdx ps desc "Customer 360"

# JSON output
tdx ps desc "Customer 360" --json

# Save to file
tdx ps desc "Customer 360" -o schema.json

# With context set (tdx ps use "Customer 360")
tdx ps desc
tdx ps desc -o schema.json
```

**Example output (stdout):**


```
Output Database: cdp_audience_12345

customers (cdp_audience_12345.customers)
┌─────────────┬─────────┐
│ Column      │ Type    │
├─────────────┼─────────┤
│ customer_id │ varchar │
│ email       │ varchar │
│ age         │ integer │
│ gender      │ varchar │
└─────────────┴─────────┘

Purchases (cdp_audience_12345.behavior_purchases)
┌──────────────┬───────────┐
│ Column       │ Type      │
├──────────────┼───────────┤
│ customer_id  │ varchar   │
│ amount       │ double    │
│ purchased_at │ timestamp │
│ time         │ bigint    │
└──────────────┴───────────┘
```

**Example output (--output):**


```
Schema saved to schema.json
  Database: cdp_audience_12345
  Tables: 1 customers + 5 behaviors
  Columns: 42 total
```

**JSON file structure (one column per line for grep):**


```json
{
  "database": "cdp_audience_12345",
  "parent_segment": "Customer 360",
  "parent_id": "12345",
  "customers": {
    "table": "customers",
    "columns": [
      { "name": "customer_id", "type": "varchar" },
      { "name": "email", "type": "varchar" },
      { "name": "age", "type": "bigint" }
    ]
  },
  "behaviors": [
    {
      "table": "behavior_purchases",
      "columns": [
        { "name": "customer_id", "type": "varchar" },
        { "name": "amount", "type": "double" },
        { "name": "time", "type": "bigint" }
      ]
    }
  ]
}
```

### sql

Get the SQL query that defines a parent segment.


```bash
tdx ps sql [name]
```

The `name` argument is optional if you have set a parent segment context with `tdx ps use`.


```bash
# Get SQL query
tdx ps sql "Customer 360"

# JSON output
tdx ps sql "Customer 360" --json

# With context set (tdx ps use "Customer 360")
tdx ps sql
```

**Example output:**


```sql
SELECT
  customer_id,
  email,
  age,
  gender
FROM cdp_audience_12345.customers
```

### show

Execute the parent segment SQL query and display results.


```bash
tdx ps show [name] [options]
```

| Option | Description |
|  --- | --- |
| `--limit <n>` | Limit number of rows (default: 100) |


The `name` argument is optional if you have set a parent segment context with `tdx ps use`.


```bash
# Show sample data
tdx ps show "Customer 360"

# Limit results
tdx ps show "Customer 360" --limit 10

# JSON output
tdx ps show "Customer 360" --json

# With context set (tdx ps use "Customer 360")
tdx ps show
tdx ps show --limit 10
```

**Example output:**


```
Query: 0.8s (100 rows)
┌─────────────┬─────────────────────┬─────┬────────┐
│ customer_id │ email               │ age │ gender │
├─────────────┼─────────────────────┼─────┼────────┤
│ C001        │ alice@example.com   │  35 │ F      │
│ C002        │ bob@example.com     │  28 │ M      │
│ C003        │ carol@example.com   │  42 │ F      │
└─────────────┴─────────────────────┴─────┴────────┘
```

## YAML Format


```yaml
name: "Customer 360"
description: "Complete customer view"

master:
  database: cdp_db
  table: customers
  filters:                      # Optional: max 2 filters
    - column: status
      values: ["active"]

schedule:
  type: daily                   # none, hourly, daily, weekly, monthly, cron
  time: "03:00"
  timezone: "America/Los_Angeles"

engine:
  hive_only: false              # false = Trino + Hive (default)
  trino_pool: null              # Optional: Trino resource pool
  hive_pool: null               # Optional: Hive resource pool

attributes:
  - name: "User Profile"        # Logical grouping name
    source:
      database: cdp_db
      table: user_profiles
    join:
      parent_key: user_id       # Key in master table
      child_key: customer_id    # Key in source table
    columns:
      - column: age             # Source column name
        label: "Age"            # Display name (optional)
        type: number
      - column: gender
        type: string

behaviors:
  - name: "Purchases"
    source:
      database: cdp_db
      table: purchase_events
    join:
      parent_key: user_id
      child_key: customer_id
    columns:
      - column: amount
        label: "Purchase Amount"
        type: number
      - column: purchased_at
        type: timestamp

  - name: "Page Views"
    source:
      database: cdp_db
      table: pageview_events
    join:
      parent_key: visitor_id
      child_key: customer_id
    all_columns: true           # Include all columns from table
```

## RT 2.0 Commands

Manage RT (Real-Time) 2.0 configuration for parent segments. RT enables real-time event processing and attribute updates for personalization use cases.


```bash
tdx ps rt <command>
```

| Command | Description |
|  --- | --- |
| [`rt list`](#rt-list) | List RT-enabled parent segments |
| [`rt validate`](#rt-validate) | Validate RT 2.0 configuration from YAML |
| [`rt configuration_versions`](#rt-configuration_versions) | Show RT configuration version status |
| [`rt jn list`](#rt-jn-list) | List RT journeys (triggers) |
| [`rt jn pause_activations`](#rt-jn-pause_activations) | Pause all activations in an RT journey |
| [`rt jn resume_activations`](#rt-jn-resume_activations) | Resume activations in a paused RT journey |


Pushing RT configuration
Use `tdx ps push` to push the full parent segment configuration including `realtime:` and `personalization_services:` sections. The diff will show exactly which sections changed.


```bash
tdx ps push customer-360      # Shows diff of all changes (including RT/PZ)
```

### rt list

List parent segments that have RT 2.0 enabled. Only shows RT-enabled segments (not all parent segments).


```bash
tdx ps rt list [pattern]
```


```bash
# List all RT-enabled parent segments
tdx ps rt list

# Filter by pattern
tdx ps rt list "Customer*"

# JSON output
tdx ps rt list --json
```

**Example output:**


```
✔ Found 2 RT-enabled parent segments
⚡ customer-360 (2.5M)
⚡ realtime-users (120K)
```

### rt validate

Validate RT 2.0 configuration from a parent segment YAML file. Checks events, attributes, ID stitching, and personalization services.


```bash
tdx ps rt validate [name]
```

The `name` argument is optional if you have set a parent segment context with `tdx ps use`.


```bash
# Validate RT config
tdx ps rt validate customer-360

# With context set
tdx ps rt validate
```

**Example output:**


```
RT 2.0 Validate: Customer 360
════════════════════════════════════════════════════════════

RT 2.0: ⚡ Enabled
  Events: 2 configured
    ✔ page_view
    ✔ purchase
  Attributes: 3 configured
    ✔ last_page_viewed (single)
    ✔ total_purchases (counter)
    ✔ last_purchase_date (single)
  ID Stitching: td_client_id + [email, phone]
  Personalization: 1 service
    - My Service
────────────────────────────────────────────────────────────

✔ RT configuration is valid
```

### rt configuration_versions

Show the current RT 2.0 configuration version status for a parent segment. Useful for checking whether a recently pushed RT configuration has been applied.


```bash
tdx ps rt configuration_versions [name]
```

The `name` argument is optional if you have set a parent segment context with `tdx ps use`.


```bash
tdx ps rt configuration_versions customer-360

# With context set
tdx ps rt configuration_versions

# JSON output
tdx ps rt configuration_versions --json
```

**Example output:**


```
id:         112
audienceId: 407586
identifier: realtime_setting
eventKind:  update
status:     completed
```

### rt jn list

List RT journeys (real-time triggers) configured for a parent segment.


```bash
tdx ps rt jn list [name]
```

The `name` argument is optional if you have set a parent segment context with `tdx ps use`.


```bash
tdx ps rt jn list customer-360

# With context set
tdx ps rt jn list

# JSON output
tdx ps rt jn list --json
```

**Example output:**


```
✔ Found 2 RT journeys
🚀 Welcome Flow (id: 88) — launched (3 stages)
📝 Re-engagement Draft (id: 91) — draft (1 stage)
```

### rt jn pause_activations

Pause all activations in an RT journey. While paused, the journey continues to process events but does not deliver activations to external systems.


```bash
tdx ps rt jn pause_activations <journeyId>
```


```bash
tdx ps rt jn pause_activations 88
```

**Example output:**


```
✔ Paused activations for journey 'Welcome Flow' (id: 88)
```

### rt jn resume_activations

Resume activations in a paused RT journey.


```bash
tdx ps rt jn resume_activations <journeyId>
```


```bash
tdx ps rt jn resume_activations 88
```

**Example output:**


```
✔ Resumed activations for journey 'Welcome Flow' (id: 88)
```

## Personalization Commands

Manage real-time personalizations for parent segments. There are two distinct concepts:

- **Personalization entities** — API-callable endpoints (`/entities/realtime_personalizations`) that return real-time personalized data based on entry criteria and payloads. Managed with `tdx ps pz` commands.
- **Personalization services** — The underlying service configuration (authentication tokens, public/private access). Managed with `tdx ps pz service` commands.



```bash
tdx ps pz <command>
```

| Command | Description |
|  --- | --- |
| [`pz list`](#pz-list) | List personalization entities |
| [`pz show`](#pz-show) | Show personalization entity details |
| [`pz create`](#pz-create) | Create a personalization entity |
| [`pz patch`](#pz-patch) | Update a personalization entity |
| [`pz delete`](#pz-delete) | Delete a personalization entity |
| [`pz init`](#pz-init) | Add template personalization section to YAML |
| [`pz service list`](#pz-service-list) | List personalization services |
| [`pz service create`](#pz-service-create) | Create a personalization service |
| [`pz service show`](#pz-service-show) | Show service details |
| [`pz service update`](#pz-service-update) | Update a service name/description |
| [`pz service delete`](#pz-service-delete) | Delete a personalization service |
| [`pz service token create`](#pz-service-token-create) | Create an access token |
| [`pz service token delete`](#pz-service-token-delete) | Delete an access token |


### pz list

List real-time personalization entities for a parent segment.


```bash
tdx ps pz list [name]
```

The `name` argument is optional if you have set a parent segment context with `tdx ps use`.


```bash
tdx ps pz list customer-360

# With context set
tdx ps pz list

# JSON output
tdx ps pz list --json
```

**Example output:**


```
✔ Found 2 personalizations
points (id: 391)
  show my points
  sections: 1
    - check points
product-recs (id: 395)
  sections: 2
    - high value
    - default
```

### pz show

Show full details of a personalization entity including all sections, entry criteria, and payloads.


```bash
tdx ps pz show <personalization_id>
```


```bash
tdx ps pz show 391
```

**Example output:**


```
points (id: 391)
  show my points
  audienceId: 407586
  created: 2025-10-15T18:41:10.423Z
  updated: 2026-02-25T23:42:08.414Z
  sections: 1
    check points (id: 1099)
      entryCriteria: enter points check
        keyEventId: 4516
      payload: {"75d5f232...": {"type": "ResponseNode", ...}}
```

### pz create

Create a new real-time personalization entity.


```bash
tdx ps pz create --name <name> --description <desc> --folder-id <id> [options]
tdx ps pz create --file <path>
```

| Option | Description |
|  --- | --- |
| `--name <text>` | Personalization name (required without `--file`) |
| `--description <text>` | Description (required without `--file`) |
| `--folder-id <id>` | Parent folder ID (required; use `null` for root folder) |
| `--audience-id <id>` | Audience (parent segment) ID — inferred from context if set |
| `--sections <json>` | Sections as an inline JSON array |
| `--file <path>` | Full request body from a JSON file (overrides other flags) |


To find the folder ID for the audience, list folders via the API:


```bash
tdx api --type cdp /audiences/<audienceId>/folders
```


```bash
# Create with flags (audience from context)
tdx ps use customer-360
tdx ps pz create --name "Product Recs" --description "Homepage recommendations" --folder-id 1046566

# Create with explicit audience ID
tdx ps pz create \
  --name "Product Recs" \
  --description "Homepage recommendations" \
  --audience-id 407586 \
  --folder-id 1046566

# Create with sections inline
tdx ps pz create \
  --name "Product Recs" \
  --description "Homepage recommendations" \
  --audience-id 407586 \
  --folder-id 1046566 \
  --sections '[{"name":"default","entryCriteria":null,"payload":null}]'

# Create from a full JSON file
tdx ps pz create --file personalization.json
```

When using `--file`, the JSON must include `relationships.parentFolder`:


```json
{
  "attributes": {
    "name": "Product Recs",
    "description": "Homepage recommendations",
    "audienceId": "407586",
    "sections": [
      {
        "name": "default",
        "entryCriteria": null,
        "payload": null
      }
    ]
  },
  "relationships": {
    "parentFolder": {
      "data": { "id": "1046566", "type": "folder-segment" }
    }
  }
}
```

**Example output:**


```
✔ Created personalization 'Product Recs' with ID: 538
```

### pz patch

Update an existing personalization entity's name, description, and/or sections.


```bash
tdx ps pz patch <personalization_id> --name <name> --description <desc> [options]
tdx ps pz patch <personalization_id> --file <path>
```

| Option | Description |
|  --- | --- |
| `--name <text>` | New name (required without `--file`) |
| `--description <text>` | New description (required without `--file`) |
| `--sections <json>` | Replacement sections as an inline JSON array |
| `--file <path>` | Full request body from a JSON file (overrides other flags) |


`--sections` replaces all sections — it is not a partial update. Omitting `--sections` clears all sections on the entity.


```bash
# Update name and description only
tdx ps pz patch 391 --name "points-v2" --description "Updated description"

# Update with new sections
tdx ps pz patch 391 \
  --name "points-v2" \
  --description "Updated" \
  --sections '[{"name":"check points","entryCriteria":{"name":"entry","keyEventCriteria":{"keyEventId":"4516","keyEventFilters":null},"profileCriteria":null},"payload":null}]'

# Update from a full JSON file
tdx ps pz patch 391 --file patch.json
```

When using `--file`, the JSON must include `attributes` with `name`, `description`, and optionally `sections`:


```json
{
  "attributes": {
    "name": "points-v2",
    "description": "Updated description",
    "sections": []
  }
}
```

**Example output:**


```
✔ Updated personalization 'points-v2' (id: 391)
```

### pz delete

Delete a personalization entity.


```bash
tdx ps pz delete <personalization_id>
```


```bash
tdx ps pz delete 391
```

**Example output:**


```
✔ Deleted personalization '391'
```

### pz init

Add a template `realtime:` and `personalization_services:` section to an existing parent segment YAML file.


```bash
tdx ps pz init [name]
```

The `name` argument is optional if you have set a parent segment context with `tdx ps use`.


```bash
tdx ps pz init customer-360

# With context set
tdx ps pz init
```

**Example output:**


```
✔ Added personalization template to parent_segments/customer-360.yml
✔ Added RT 2.0 template section

Next steps:
  1. Edit parent_segments/customer-360.yml to configure your personalization service
  2. Run tdx ps push customer-360 to push the configuration
```

The generated template adds these sections to your YAML:


```yaml
realtime:
  events:
    - name: page_view
      source_table: <database>.<table>
  attributes:
    - name: last_page_viewed
      type: single
  id_stitching:
    primary_key: td_client_id

personalization_services:
  - name: My Service
    description: Personalization service description
    trigger_event: page_view
    sections:
      - name: Default
        criteria: "true"
        attributes:
          - last_page_viewed
```

### pz service list

List personalization services for a parent segment. Services provide authentication tokens and access control for personalization API calls.


```bash
tdx ps pz service list [name]
```

The `name` argument is optional if you have set a parent segment context with `tdx ps use`.


```bash
tdx ps pz service list customer-360

# With context set
tdx ps pz service list

# JSON output
tdx ps pz service list --json
```

**Example output:**


```
✔ Found 1 personalization service
My Service (id: svc_123)
  Personalized homepage content
  Tokens:
    prod-token (id: tok_456) — IPs: any
```

### pz service create

Create a new personalization service for a parent segment.


```bash
tdx ps pz service create <name> [parent_segment]
```

| Option | Description |
|  --- | --- |
| `--description <text>` | Service description |
| `--public` | Make service public (default: private) |



```bash
tdx ps pz service create "My Service" customer-360 --description "Homepage personalizations"

# With context set
tdx ps pz service create "My Service"
```

**Example output:**


```
✔ Created personalization service 'My Service' with ID: svc_123
```

### pz service show

Show details of a personalization service including tokens and IP restrictions.


```bash
tdx ps pz service show <service_id> [parent_segment]
```


```bash
tdx ps pz service show svc_123 customer-360

# With context set
tdx ps pz service show svc_123
```

### pz service update

Update the name and/or description of a personalization service.


```bash
tdx ps pz service update <service_id> [parent_segment]
```

| Option | Description |
|  --- | --- |
| `--name <name>` | New service name (required) |
| `--description <text>` | New description |



```bash
tdx ps pz service update svc_123 --name "My Service v2" --description "Updated description"
```

### pz service delete

Delete a personalization service and all its tokens.


```bash
tdx ps pz service delete <service_id> [parent_segment]
```


```bash
tdx ps pz service delete svc_123
```

### pz service token create

Create an access token for a personalization service. The token value is shown **once** at creation time — save it immediately.


```bash
tdx ps pz service token create <name> <service_id> [parent_segment]
```

| Option | Description |
|  --- | --- |
| `--allowed-ips <ips>` | Comma-separated list of allowed IP addresses |
| `--description <text>` | Token description |



```bash
tdx ps pz service token create "prod-token" svc_123 customer-360

# With IP restrictions
tdx ps pz service token create "prod-token" svc_123 --allowed-ips "10.0.0.1,10.0.0.2"

# With context set
tdx ps pz service token create "prod-token" svc_123
```

The token value is only displayed once on creation. Store it securely — it cannot be retrieved again.

**Example output:**


```
✔ Created token 'prod-token' with ID: tok_456

⚠ Save this token value — it will not be shown again:
  eyJhbGci...
```

### pz service token delete

Delete a token from a personalization service.


```bash
tdx ps pz service token delete <token_id> [parent_segment]
```


```bash
tdx ps pz service token delete tok_456
```

## RT 2.0 YAML Format

The `realtime:` and `personalization_services:` sections are added to the parent segment YAML alongside the existing `master:`, `attributes:`, and `behaviors:` sections.


```yaml
name: "Customer 360"

master:
  database: cdp_db
  table: customers

# ... attributes, behaviors, schedule ...

realtime:
  events:
    - name: page_view                     # Event name (required)
      source_table: web_db.pageviews      # Source table reference
    - name: purchase
      source_table: sales_db.transactions
      filter_pattern: "status=completed"  # Optional filter

  attributes:
    - name: last_page_viewed              # Attribute name (required)
      type: single                        # single, counter, set, ordered_set, list, imported_batch
      source_event: page_view             # Source event
      source_field: page_url              # Field from source event
    - name: total_purchases
      type: counter
    - name: recent_categories
      type: set

  id_stitching:
    primary_key: td_client_id             # Primary key (required)
    stitching_keys:                       # Additional keys for identity resolution
      - email
      - phone
    exclusion_patterns:                   # Patterns to exclude
      - "bot_*"

personalization_services:
  - name: Product Recommendations         # Service name (required)
    description: Personalized products    # Description
    trigger_event: page_view              # Event that triggers the service
    sections:
      - name: High Value                  # Section name
        criteria: "total_purchases > 10"  # Criteria expression
        attributes:                       # Attributes to serve
          - last_page_viewed
          - recent_categories
        batch_segments:                   # Batch segment names to include
          - VIP Customers
      - name: Default
        criteria: "true"                  # Catch-all section
        attributes:
          - last_page_viewed
```

### RT attribute types

| Type | Description |
|  --- | --- |
| `single` | Latest value (overwrites on each event) |
| `counter` | Incrementing count |
| `set` | Unordered set of unique values |
| `ordered_set` | Ordered set of unique values |
| `list` | API alias for `set` |
| `imported_batch` | Batch-imported attribute from parent segment |