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


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


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


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


```bash
# 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:**


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


```json
{
  "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"` |


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:


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


```bash
# 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