# connection

Manage result output connections used for exporting job results and segment activations.

## Overview


```mermaid
flowchart LR
    subgraph Type["Connector Type"]
        Settings["Settings<br/><small>credentials, auth</small>"]
        Schema["Schema<br/><small>output options</small>"]
    end

    Settings -->|creates| Connection
    Schema -->|configures| Activation["Activation<br/><small>connector_config</small>"]
    Connection -->|used by| Activation

    CmdSettings["tdx connection settings"] -.-> Settings
    CmdSchema["tdx connection schema"] -.-> Schema
    CmdListShow["tdx connection list/show"] -.-> Connection

    style Settings fill:#e1f5fe
    style Schema fill:#fff3e0
    style Connection fill:#e8f5e9
    style Activation fill:#fce4ec
```

**Two types of configuration:**

- **Settings** - Credentials and auth needed to *create* a connection
- **Schema** - Options for `connector_config` when *using* a connection in activations


## Commands

| Command | Description |
|  --- | --- |
| `tdx connection list` | List all result output connections |
| `tdx connection show <name>` | Show connection details |
| `tdx connection types` | List available connector types |
| `tdx connection schema <type>` | Show connector output schema for `connector_config` in activations |
| `tdx connection settings <type>` | Show connection-level settings (credentials, authentication) |


## Usage

### List Connections

List all result output connections available in your account:


```bash
# List all connections (simple format: name, type, owner)
tdx connection list

# Output in table format (detailed view)
tdx connection list --table

# Output as JSON
tdx connection list --json

# Limit results
tdx connection list --limit 10
```

**Default output format:**


```
        s3  my-s3-export - John Doe
salesforce  salesforce-sync - Jane Smith
  bigquery  bigquery-warehouse - Data Team
```

### Show Connection

Show detailed information about a specific connection by name:


```bash
# Show by name
tdx connection show my-s3-connection

# Output as JSON
tdx connection show "My Salesforce Connection" --json
```

### List Connector Types

List all available connector types for activations:


```bash
# List all connector types
tdx connection types

# Output as JSON
tdx connection types --json
```

**Default output format:**


```
           s3  S3
       pgsql  PostgreSQL
  salesforce  Salesforce
    bigquery  BigQuery
```

### Show Connector Schema

Show the output schema for a connector type. This shows what fields are available in `connector_config` when configuring **activations**:


```bash
# Show schema for salesforce connector
tdx connection schema salesforce

# Show schema for s3
tdx connection schema s3

# Output as JSON (full schema)
tdx connection schema salesforce --json
```

**Default output format:**


```
Connector: salesforce

Available fields:
  object: Object Name [text]
    Salesforce object name (e.g., Contact, Lead, Account)
  mode: Mode [select]
    Options: append, replace, upsert
    Default: append
  external_id_field: External ID Field [text]
    Show when: mode=["upsert"]
```

Using with Activations
The schema shows available fields for the `connector_config` section in activation YAML:


```yaml
activations:
  - name: SFMC Export
    connection: my-sfmc
    connector_config:
      de_name: CustomerSegment
      shared_data_extension: false
```

When you run `tdx sg push` or `tdx journey push`, the `connector_config` is automatically validated against the schema. Invalid values will be caught with helpful error messages before pushing to TD.

### Show Connection Settings

Show the connection-level settings for a connector type. This shows what credentials and configuration are needed when **creating a connection**:


```bash
# Show settings for REST API connector
tdx connection settings rest

# Show settings for S3
tdx connection settings s3

# Output as JSON (full metadata)
tdx connection settings rest --json
```

**Default output format:**


```
Connector: rest
Name: REST API (For internal CDP KVS server only)

Credential settings:
  endpoint: Endpoint
    HTTP Request endpoint

Available fields:
  method: HTTP Method [select]
    HTTP Method to use in request
    Options: PUT, POST, PATCH
    Default: POST
  headers: Request headers
    JSON map of headers name/value to be included in request
```

Schema vs Settings
- **`schema`** - Output settings for `connector_config` in activations (what to send)
- **`settings`** - Connection-level settings (credentials, endpoints, authentication)


Some connectors (like `rest`) only have connection settings and no output schema.

## Aliases

- `tdx connections` - Alias for `tdx connection list`


## Output Fields

### Connection List/Details

| Field | Description |
|  --- | --- |
| `name` | Connection name (unique identifier) |
| `type` | Connection type (e.g., s3, td, postgresql, gspreadsheet) |
| `settings` | Connection settings (JSON object) or URL string |
| `organization` | Organization (deprecated) |


## Examples


```bash
# List connections and filter with jq
tdx connection list --json | jq '.[] | select(.name | contains("s3"))'

# Export connection list to a file
tdx connection list --json > connections.json

# Check what credentials are needed for a connector
tdx connection settings salesforce

# Check what output options are available for activations
tdx connection schema salesforce
```