Profile Management
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
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

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

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

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.

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:

CLI flags (highest priority) — --database, --profile, --site, etc.
Session context — Shell-scoped overrides set with tdx use
Environment variables — TDX_PROFILE, TDX_SITE for CI/CD environments
Project config — Per-project defaults in ./tdx.json
Profile config — Settings in ~/.config/tdx/tdx.json for the active profile
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):

TDX_API_KEY_<NORMALIZED_PROFILE> environment variable
Profile keychain credential
TDX_API_KEY environment variable (CI/CD fallback)

When no profile:

TDX_API_KEY environment variable
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:

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:

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

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

Explicit Session ID

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

TDX_SESSION Environment Variable

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

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

Profile ManagementCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code