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

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

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

# 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

See CI/CD Configuration for complete setup examples.

Working with Profiles

Profile Commands

The tdx profile command group provides all profile management operations:

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

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

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

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

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

Clearing Context

Use tdx unset to clear session or default context values:

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

# 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

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

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

# 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

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 --profile is specified:

1. TDX_API_KEY_<PROFILE> environment variable
2. Profile keychain credential
3. TDX_API_KEY environment variable

When no profile:

1. TDX_API_KEY environment variable
2. Default keychain credential

View Context

See the currently resolved context and where each value comes from:

# Show current context
tdx use

# Show context with sources (debugging)
tdx use --debug

Example output:

[context]
site: us01 (global: ~/.config/tdx/tdx.json)
database: analytics (session)
llm_project: DataAnalytics (profile: production)
profile: production (session)

Configuration Files:
  Session: /Users/user/.config/tdx/sessions/12345.json ✓
  Global: /Users/user/.config/tdx/tdx.json ✓
  Project: /Users/user/projects/myproject/tdx.json ✓

Advanced: Session ID Option

By default, sessions are tied to the shell's process ID (PPID). You can explicitly specify a session ID using --session to share context across multiple processes or shells:

# 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

Use cases:

• Sharing context between multiple terminal windows
• Maintaining consistent context in CI/CD pipelines
• Scripting scenarios where session persistence is needed