Context Management

tdx provides a unified context system to reduce repetitive flags across commands.

Context Resolution Order

Context is resolved from multiple sources with the following priority:

1. CLI flags (highest priority) - --database, --parent-segment, etc.
2. Session context - Shell-scoped overrides set with tdx use (identified by PPID)
3. Project config - Per-project defaults in ./tdx.json
4. Profile config - Settings in ~/.config/tdx/tdx.json (inside profiles object), applied when --profile <name> or tdx use profile <name> is set
5. Global config - Fallback defaults in ~/.config/tdx/tdx.json (top-level settings)

Profiles

Profiles store long-lived account configurations for easy switching between environments:

# List all profiles with details
tdx profiles

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

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

# Or use --profile for one-off commands
tdx --profile production databases
tdx --profile production tables mydb
tdx --profile production query "SELECT * FROM mydb.users LIMIT 10"
tdx --profile production auth   # Check auth status for profile

Profile Structure

Profiles are defined in ~/.config/tdx/tdx.json with a profiles object. When you run tdx auth setup --profile <name>, the profile entry is automatically created or updated.

For manual configuration or to add additional settings 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"
    }
  }
}

Setting Up Authentication for Profiles

Use tdx auth setup --profile <name> to configure API credentials for a specific profile:

# Set up API key for production profile
tdx auth setup --profile production

# Set up API key for dev profile
tdx auth setup --profile dev

This stores the API key securely in the system keychain, associated with the profile name.

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

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 (e.g., GitHub) so all team members use the same defaults

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

Available Parameters

Parameter	Type	Description	Example
description	string	Optional description	"Production environment"
site	string	TD site/region	"us01"
database	string	Default database	"analytics"
parent_segment	string	Default parent segment	"active_users"
llm_project	string	Default LLM project	"DataAnalytics"

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 ✓

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