Profile Management

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

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

# 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

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

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

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

# Or use an access token (Bearer auth, takes precedence over API key)
export TDX_ACCESS_TOKEN=your-access-token-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.

The tdx profile command group provides all profile management operations:

# List all profiles
tdx profile list

# Create a new profile
tdx profile create staging

# Delete a profile
tdx profile delete 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"

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

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"
    }
  }
}

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

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

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

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

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

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)

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"
}

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)"
    }
  }
}

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

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.

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

When tdx needs a credential, it checks sources in this order:

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

1. TDX_ACCESS_TOKEN_<NORMALIZED_PROFILE> environment variable (Bearer auth)
2. TDX_ACCESS_TOKEN environment variable (Bearer auth)
3. TDX_API_KEY_<NORMALIZED_PROFILE> environment variable
4. Profile keychain credential
5. TDX_API_KEY environment variable (CI/CD fallback)

When no profile:

1. TDX_ACCESS_TOKEN environment variable (Bearer auth)
2. TDX_API_KEY environment variable
3. Default keychain credential

When an access token is present, tdx uses Authorization: Bearer <token> instead of Authorization: TD1 <apikey>. This is useful for environments where OAuth tokens are provisioned externally.

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

• production → TDX_API_KEY_PRODUCTION / TDX_ACCESS_TOKEN_PRODUCTION
• my-test-profile → TDX_API_KEY_MY_TEST_PROFILE
• @tdx-studio:us01:7060 → TDX_API_KEY__TDX_STUDIO_US01_7060

A profile's credential (API key or OAuth token) is issued for a single site — there's no way to reuse one profile's credential across multiple sites. The --site flag, the tdx use site / tdx use --default site overrides, and TDX_SITE only re-target which region's API endpoint a command talks to; none of them change which credential gets sent.

If the active profile has a recorded site in tdx.json and the resolved site (from any source in Context Resolution Order above) differs from it, tdx fails fast with an error naming the profile, both sites, and which source supplied the conflicting site — instead of sending the request and getting a confusing 401 from the wrong region. To resolve a mismatch:

• Switch to a profile bound to the resolved site: tdx profile use <name>
• Set up a new profile for that site: tdx auth setup --site <site> --profile <name>
• Drop the override so the active profile's own site is used

This check only applies when a profile is active and has a recorded site — env-var credentials (TDX_API_KEY with no active profile) and profiles created before this check existed (no recorded site) are unaffected. Note that because a profile's own config outranks the global default in the resolution order, tdx use --default site <x> can only ever conflict with an inactive profile, never the active one — setting a default while a mismatched profile is active just prints a warning that the default has no effect until you switch away from that profile.

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

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

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

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