Skip to content
Treasure Code
/
/
Context Management
Last updated

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, --site, 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 - Account-specific settings
  5. Global config - Fallback defaults in ~/.config/tdx/tdx.json

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

Profile Structure

Profiles are defined in tdx.json files with a profiles object:

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

Profile Locations

  • User-level: ~/.config/tdx/tdx.json - Shared across all projects
  • Project-level: (project folder)/tdx.json - Project-specific profiles

Profile Precedence

  1. Project tdx.json profiles (local)
  2. User ~/.config/tdx/tdx.json profiles (user-level)

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 context

# Clear session context
tdx context --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:

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

Available Parameters

ParameterTypeDescriptionExample
descriptionstringOptional description"Production environment"
sitestringTD site/region"us01"
databasestringDefault database"analytics"
parent_segmentstringDefault parent segment"active_users"
llm_projectstringDefault LLM project"DataAnalytics"
Security Note

Project configs should never contain API keys since they may be committed to version control. Use profiles or global .env files for credentials.

View Context

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

# Show current context
tdx context

# Show context with sources (debugging)
tdx context --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
Previous page
Next page