# Profile Management

`tdx` uses profiles to manage multiple Treasure Data accounts and environments. Each profile stores authentication credentials, region settings, and default configurations.

## What is a Profile?

A profile is a named configuration that includes:

- **Authentication** — API key stored securely in your system keychain
- **Region** — Which TD site to connect to (us01, jp01, eu01, ap02)
- **Defaults** — Optional settings like default database or LLM project


## Quick Start


```bash
# Create a new profile
tdx profile create production

# List all profiles
tdx profile list

# Switch to a profile for the current session
tdx profile use production

# Or use --profile for one-off commands
tdx --profile staging databases
```

## Creating a Profile

Use `tdx profile create` to set up a new profile with authentication:


```bash
# Create with name
tdx profile create production

# Or fully interactive
tdx profile create
```

The command will:

- Guide you through site selection (us01, jp01, eu01, ap02)
- Prompt for an optional description
- Securely prompt for your API key
- Validate the API key before saving
- Save credentials to your system keychain


### Credential Storage

API keys are stored securely in your operating system's keychain:

| Platform | Storage Location |
|  --- | --- |
| macOS | Keychain Access |
| Windows | Credential Manager |
| Linux | Secret Service (libsecret) |


### Environment Variables

For CI/CD pipelines or headless environments where keychain is unavailable, use environment variables:


```bash
# Set the active profile
export TDX_PROFILE=production

# Set the API key
export TDX_API_KEY=your-api-key-here

# [Advanced] Set the site/region (optional, overrides profile setting)
export TDX_SITE=us01

# [Advanced] Set a stable session ID (useful for IDE terminals where PPID varies)
export TDX_SESSION=my-session
```

See [CI/CD Configuration](#ci-cd-configuration) for complete setup examples.

## Working with Profiles

### Profile Commands

The `tdx profile` command group provides all profile management operations:


```bash
# List all profiles
tdx profile list

# Create a new profile
tdx profile create staging

# Remove a profile
tdx profile remove staging


# Set session profile (for current shell)
tdx profile use production

# Set profile configuration (uses session profile, or specify with --profile)
tdx profile set database=analytics
tdx profile set description="Production environment"
```

### Using Profiles

Once you have profiles set up, you can switch between them easily:


```bash
# Set session profile (shell-scoped)
tdx profile use production

# Set profile as permanent default (saves to ~/.config/tdx/tdx.json)
tdx profile use production --default

# Once profile is set, no --profile flag needed
tdx databases
tdx tables mydb
tdx query "SELECT * FROM mydb.users LIMIT 10"

# Or use --profile for one-off commands
tdx --profile staging databases
```

### Profile Structure

Profiles are defined in `~/.config/tdx/tdx.json`. When you run `tdx profile create`, the profile entry is automatically created.

You can also manually edit the file to add defaults like `database` or `llm_project`:


```json
{
  "profiles": {
    "production": {
      "description": "Production environment for US region",
      "site": "us01",
      "database": "analytics",
      "llm_project": "DataAnalytics"
    },
    "dev": {
      "description": "Development and testing environment",
      "site": "jp01",
      "database": "dev_db"
    }
  }
}
```

### Available Parameters

These parameters can be set via `tdx profile set <key>=<value>` (uses session profile) or by editing `tdx.json`:

| Parameter | Type | Description | Example |
|  --- | --- | --- | --- |
| `description` | string | Optional description | `"Production environment"` |
| `site` | string | TD site/region (requires API key validation) | `"us01"` |
| `database` | string | Default database | `"analytics"` |
| `parent_segment` | string | Default parent segment | `"active_users"` |
| `llm_project` | string | Default LLM project | `"DataAnalytics"` |
| `llm_agent` | string | Default LLM agent | `"Assistant"` |


## Session Context

Set temporary overrides for the current shell session:


```bash
# Set session database
tdx use database mydb

# Set session LLM project
tdx use llm_project Analytics

# View current context
tdx use

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

### Saving Default Profile

Use `--default` to save the default profile permanently to `~/.config/tdx/tdx.json`:


```bash
# Save default profile (persists across sessions)
tdx use --default profile production
```

### Clearing Context

Use `tdx unset` to clear session or default context values:


```bash
# Clear session database
tdx unset database

# Clear session profile
tdx unset profile

# Clear default profile from config
tdx unset --default profile
```

Resources available for session context: `database`, `parent_segment`, `llm_project`, `agent`, `profile`, `engage_workspace`

### How Session Scope Works

Sessions are automatically scoped to your current shell window. Each terminal window/tab has a unique process ID (PID), and `tdx` uses the parent process ID (PPID) to identify and isolate sessions.

- **Automatic isolation**: Each terminal window maintains its own independent session context
- **No manual setup**: Sessions are created automatically when you run `tdx use` commands
- **Persistent within shell**: Context persists across multiple commands in the same terminal
- **Automatic cleanup**: Sessions expire after 24 hours or when the shell is closed


**Example:**


```bash
# Terminal Window 1
tdx use database analytics
tdx tables  # Uses database: analytics

# Terminal Window 2 (different PID)
tdx tables  # Uses default database (separate session)
```

## Project Config

Store per-project defaults in `tdx.json` at your project root. This is useful for:

- **Per-folder database settings**: Different projects can use different databases without manual switching
- **Shared team configuration**: Commit `tdx.json` to version control so all team members use the same defaults



```json
{
  "database": "customer_analytics",
  "parent_segment": "active_users",
  "llm_project": "CustomerInsights"
}
```

## CI/CD Configuration

For automated pipelines, combine project config with environment variables.

### Share Profile Settings via tdx.json

Commit profile configurations in your project's `tdx.json` so CI/CD uses the same settings as your team:


```json
{
  "profile": "production",
  "profiles": {
    "production": {
      "site": "us01",
      "database": "analytics",
      "parent_segment": "Customer 360"
    },
    "staging": {
      "site": "us01",
      "database": "staging_db",
      "parent_segment": "Customer 360 (Staging)"
    }
  }
}
```

### Set Profile, Site, and API Key via Environment Variables

In your CI/CD platform, set the profile and API key as secrets:


```bash
# Set the active profile
export TDX_PROFILE=production

# Set API key (profile-specific recommended)
export TDX_API_KEY_PRODUCTION=${{ secrets.TDX_API_KEY_PRODUCTION }}

# Or generic (used when no profile specified)
export TDX_API_KEY=${{ secrets.TDX_API_KEY }}

# [Advanced] Set the site/region (optional, overrides profile setting)
export TDX_SITE=us01
```

Profile names in `TDX_API_KEY_<PROFILE>` are normalized: uppercase with non-alphanumeric characters replaced by underscores.

- `TDX_PROFILE=production` → `TDX_API_KEY_PRODUCTION`
- `TDX_PROFILE=my-test-profile` → `TDX_API_KEY_MY_TEST_PROFILE`


### Example: GitHub Actions


```yaml
jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install tdx
        run: npm install -g @treasuredata/tdx

      - name: Deploy to staging
        env:
          TDX_PROFILE: staging
          TDX_API_KEY_STAGING: ${{ secrets.TDX_API_KEY_STAGING }}
        run: |
          tdx sg push --dry-run
          tdx sg push

  deploy-production:
    runs-on: ubuntu-latest
    needs: deploy-staging
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install tdx
        run: npm install -g @treasuredata/tdx

      - name: Deploy to production
        env:
          TDX_PROFILE: production
          TDX_API_KEY_PRODUCTION: ${{ secrets.TDX_API_KEY_PRODUCTION }}
        run: |
          tdx sg push --dry-run
          tdx sg push
```

The `tdx.json` in your repo provides `site`, `database`, and `parent_segment` for each profile. The environment variables provide profile selection and authentication.

## Context Resolution Order

When you run a command, `tdx` resolves settings from multiple sources:

1. **CLI flags** (highest priority) — `--database`, `--profile`, `--site`, etc.
2. **Session context** — Shell-scoped overrides set with `tdx use`
3. **Environment variables** — `TDX_PROFILE`, `TDX_SITE` for CI/CD environments
4. **Project config** — Per-project defaults in `./tdx.json`
5. **Profile config** — Settings in `~/.config/tdx/tdx.json` for the active profile
6. **Global config** (lowest priority) — Fallback defaults


### Credential Resolution Priority

When tdx needs an API key, it checks sources in this order:

**When a profile is active** (via `--profile`, session, config, or `TDX_PROFILE`):

1. `TDX_API_KEY_<NORMALIZED_PROFILE>` environment variable
2. Profile keychain credential
3. `TDX_API_KEY` environment variable (CI/CD fallback)


**When no profile:**

1. `TDX_API_KEY` environment variable
2. Default keychain credential


Profile names are normalized for environment variables: uppercase with non-alphanumeric characters replaced by underscores.

- `production` → `TDX_API_KEY_PRODUCTION`
- `my-test-profile` → `TDX_API_KEY_MY_TEST_PROFILE`
- `@tdx-studio:us01:7060` → `TDX_API_KEY__TDX_STUDIO_US01_7060`


## View Context

Use `tdx status` to see authentication, context, and configuration all at once:


```bash
tdx status
```

Example output:


```
tdx profile: production (from CLI flag) (site: us01)
Read credential from keychain (profile: production)
✓ Authentication successful

User: user@example.com
Name: John Doe
Account ID: 12345

[context]
site: us01 (profile: production)
database: analytics (session)
llm_project: DataAnalytics (profile: production)
profile: production (active)

[configuration files]
Session: /Users/user/.config/tdx/sessions/12345.json ✓ (session: 12345)
Project: none
Global: /Users/user/.config/tdx/tdx.json ✓
```

The profile source shows where the profile was selected from:

- `(from CLI flag)` — Set via `--profile` option
- `(from session)` — Set via `tdx profile use`
- `(from config)` — Set as default in `~/.config/tdx/tdx.json`
- `(from TDX_PROFILE env)` — Set via environment variable


You can also use `tdx use` to view or modify context:


```bash
# Show current context only
tdx use

# Set session database
tdx use database mydb
```

## Advanced: Session ID Option

Session ID is resolved in this priority order:

1. **`--session` flag** (highest) — Explicit per-command override
2. **`TDX_SESSION` env var** — Stable identity for IDE terminals
3. **Parent PID** (default) — Automatic per-shell isolation


### Explicit Session ID

Use `--session` to share context across multiple processes or shells:


```bash
# Process 1: Set session with explicit ID
tdx --session my-workflow use database analytics

# Process 2: Reuse the same session
tdx --session my-workflow tables
# Uses database: analytics
```

### TDX_SESSION Environment Variable

Set `TDX_SESSION` for stable sessions in environments where PPID varies (IDE terminals, Treasure Studio):


```bash
export TDX_SESSION=my-workspace
tdx use database analytics
tdx tables  # Uses database: analytics
```

Use cases:

- Sharing context between multiple terminal windows
- Maintaining consistent context in IDE terminals and Treasure Studio
- CI/CD pipelines and scripting scenarios where session persistence is needed