@treasuredata/tdx 0.1.4 → 0.1.5

package/README.md

@@ -11,42 +11,6 @@ A modern, AI-native command-line interface for Treasure Data, optimized for both
 - 🚀 **Modern Distribution**: Install via `npx` or `npm` without prior setup
 - ⚡ **Fast & Efficient**: Built with TypeScript on Node.js 24+
 
-## Architecture
-
-The `tdx` project is designed with a layered architecture that separates the CLI interface from the core SDK, allowing the TypeScript SDK to be used in multiple environments:
-
-```mermaid
-graph TD
-    subgraph "Client Environments"
-        NodeJS[Node.JS/CLI<br/>tdx commands]
-        Browser[Web Browser<br/>Client-side]
-    end
-
-    subgraph "TDX SDK - TypeScript"
-        SDK[TDX SDK<br/>TypeScript/JavaScript API]
-    end
-
-    subgraph "Treasure Data APIs"
-        TD[TD REST API<br/>Databases, Tables, Jobs]
-        Trino[Trino Streaming API<br/>Query Execution]
-        CDP[CDP API<br/>Segments, Activations]
-    end
-
-    NodeJS --> SDK
-    Browser --> SDK
-
-    SDK -->|HTTPS| TD
-    SDK -->|HTTPS| Trino
-    SDK -->|HTTPS| CDP
-
-    style NodeJS fill:#d4f1d4
-    style Browser fill:#ffd4d4
-    style SDK fill:#fff5cc
-    style TD fill:#e8e8f0
-    style CDP fill:#e8e8f0
-    style Trino fill:#e8e8f0
-```
-
 ## Installation
 
 ```bash
@@ -115,8 +79,154 @@ tdx databases --format table
 # Chat with AI (simplified - uses default agent)
 tdx chat "Show me customer revenue trends"
 
-# Continue previous chat
-tdx chat --continue "What about last month?"
+# Continue previous chat (default behavior)
+tdx chat "What about last month?"
+
+# Start a new chat session
+tdx chat --new "Tell me about data pipelines"
+```
+
+## Context Management
+
+`tdx` provides a unified context system to reduce repetitive flags across commands. 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`
+3. **Project config** - Per-project defaults in `tdx.json`
+4. **Profile config** - Account-specific settings in `~/.config/tdx/profiles/<name>/tdx.json`
+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
+
+# Switch active profile
+tdx use profile production
+```
+
+**Profile Structure:**
+
+```
+~/.config/tdx/profiles/
+  ├── production/
+  │   ├── tdx.json      # Configuration (site, database, llm_project, etc.)
+  │   └── .env          # Credentials (TD_API_KEY)
+  └── dev/
+      ├── tdx.json      # Development environment config
+      └── .env          # Development credentials
+```
+
+**Example Production Profile** (`~/.config/tdx/profiles/production/tdx.json`):
+```json
+{
+  "description": "Production environment for US region",
+  "site": "us01",
+  "database": "analytics",
+  "llm_project": "DataAnalytics"
+}
+```
+
+**Example Development Profile** (`~/.config/tdx/profiles/dev/tdx.json`):
+```json
+{
+  "description": "Development and testing environment",
+  "site": "jp01",
+  "database": "dev_db"
+}
+```
+
+**Note:** The `description` field is optional but recommended for documenting what each profile is for.
+
+### 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
+
+# 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. This means:
+
+- **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)
+```
+
+Session context persists until the shell is closed or explicitly cleared with `tdx use --clear`.
+
+**Note:** For advanced session sharing across multiple processes or shells, see [Session ID Option](#session-id-option) in the Advanced Options section.
+
+### 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 Configuration Parameters:**
+
+| Parameter | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `description` | string | Optional description of the configuration | `"Production environment"` |
+| `site` | string | TD site/region (us01, jp01, eu01, ap02) | `"us01"` |
+| `database` | string | Default database for queries and table commands | `"analytics"` |
+| `parent_segment` | string | Default parent segment for CDP commands | `"active_users"` |
+| `llm_project` | string | Default LLM project for agent commands | `"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 (active)
+
+Configuration Files:
+  Session: /Users/user/.config/tdx/sessions/12345.json ✓
+  Profile: /Users/user/.config/tdx/profiles/production/tdx.json ✓
+  Global: /Users/user/.config/tdx/tdx.json ✓
 ```
 
 ## Available Commands
@@ -181,20 +291,23 @@ Simplified top-level command for chatting with LLM agents.
 
 | Command | Description | Example |
 |---------|-------------|---------|
-| `chat <message>` | Chat with default agent (claude-4.5-sonnet) | `tdx chat "Analyze my data"` |
+| `chat <message>` | Chat (continues last session by default) | `tdx chat "Analyze my data"` |
 | `chat <message> --agent <ref>` | Chat with specific agent | `tdx chat "Hello" --agent "Project/Agent"` |
 | `chat <message> --model <name>` | Chat using specific model | `tdx chat "Help" --model "gpt-5"` |
 | `chat <message> --temperature <n>` | Set temperature (0.0-2.0, default: 0.7) | `tdx chat "Be creative" --temperature 1.2` |
-| `chat <message> --continue` (or `-c`) | Continue last chat session | `tdx chat -c "What else?"` |
+| `chat <message> --new` | Start a new chat session | `tdx chat --new "Fresh conversation"` |
 
 **Examples**:
 ```bash
 # Simple chat (uses default agent with claude-4.5-sonnet)
 tdx chat "Show me the top customers by revenue"
 
-# Continue previous conversation
-tdx chat --continue "What about last quarter?"
-tdx chat -c "And the quarter before that?"
+# Continue previous conversation (default behavior)
+tdx chat "What about last quarter?"
+tdx chat "And the quarter before that?"
+
+# Start a new conversation
+tdx chat --new "Tell me about data modeling best practices"
 
 # Use specific agent
 tdx chat "Analyze churn" --agent "MyProject/Data Analyst"
@@ -213,113 +326,13 @@ tdx chat "Hello" --verbose
 ```
 
 **How it works**:
-- **Default behavior**: Uses `tdx_default` project and agent (auto-created with temperature: 0.7)
+- **Default behavior**: Continues last chat session automatically (or creates new if none exists)
 - **Session persistence**: Last chat ID saved to `.cache/tdx/last_chat_id`
-- **--continue flag**: Resumes last chat automatically
+- **--new flag**: Starts a fresh chat session
 - **--agent**: Use specific agent (requires `"project/agent"` format)
 - **--model**: Reuses or creates agent per model (e.g., `tdx_gpt-5`)
 - **--temperature**: Controls randomness (0.7 default, lower=focused, higher=creative)
 
-### API Command (Raw HTTP Access)
-
-Make authenticated HTTP requests to any Treasure Data API endpoint (similar to `gh api` from GitHub CLI).
-
-**Usage:** `tdx api <endpoint> [options]`
-
-| Option | Description | Example |
-|--------|-------------|---------|
-| `<endpoint>` | API endpoint path (must start with /) | `/v3/database/list` |
-| `-X, --method <method>` | HTTP method (GET, POST, PUT, DELETE, PATCH) | `-X POST` |
-| `--data <json>` | Request body as JSON string | `--data '{"name":"mydb"}'` |
-| `-f, --file <path>` | Read request body from file | `-f body.json` |
-| `-H, --header <header>` | Custom header (repeatable) | `-H "X-Custom: value"` |
-| `--type <api_type>` | API type (td, cdp, workflow, trino, llm) | `--type cdp` |
-
-**Examples:**
-
-```bash
-# GET request to TD API (default)
-tdx api /v3/database/list
-
-# GET with path parameters
-tdx api /v3/database/show/mydb
-tdx api /v3/table/list/mydb
-tdx api /v3/table/show/mydb/users
-
-# POST with inline JSON body (submit query)
-tdx api -X POST --data '{"query":"SELECT 1"}' /v3/job/issue/hive/mydb
-
-# POST with data from file
-tdx api -X POST -f query.json /v3/job/issue/hive/mydb
-
-# Custom headers
-tdx api -H "X-Custom: value" -H "X-Another: test" /v3/database/list
-
-# CDP API endpoints (read-only)
-tdx api /entities/parent_segments --type cdp
-tdx api /audiences/12345/segments --type cdp
-tdx api -X POST --data '{"format":"sql"}' /audiences/12345/segments/query --type cdp
-
-# Workflow API endpoints (read-only)
-tdx api /api/workflows --type workflow
-tdx api /api/projects --type workflow
-tdx api /api/attempts --type workflow
-
-# Trino API endpoints (query submission - plain SQL, not JSON)
-tdx api -X POST --data 'SELECT 1' /v1/statement --type trino
-
-# LLM API endpoints (read-only)
-tdx api /v1/agents --type llm
-tdx api /v1/models --type llm
-
-# Show HTTP response headers (with --verbose)
-tdx api /v3/database/list --verbose
-
-# Save output to file
-tdx api /v3/database/list --output databases.json
-
-# Combine --verbose with --output to see headers while saving
-tdx api /v3/database/list --verbose --output databases.json
-```
-
-**API Types:**
-
-| Type | Base URL Pattern | Description |
-|------|-----------------|-------------|
-| `td` | `api.treasuredata.com` | TD REST API (databases, tables, jobs) |
-| `cdp` | `api-cdp.treasuredata.com` | CDP API (audiences, segments, activations) |
-| `workflow` | `api-workflow.treasuredata.com` | Workflow API (digdag) |
-| `trino` | `api-presto.treasuredata.com` | Trino Query Engine API |
-| `llm` | `llm-api.treasuredata.com` | LLM API (agents, chat) |
-
-**Notes:**
-- All requests are automatically authenticated using your configured API key
-- Request body from `--data` must be valid JSON
-- `--data` and `--file` are mutually exclusive
-- Custom headers override default authentication headers
-- Response is output to stdout as JSON
-- Use `--verbose` to show HTTP request/response details in stderr:
-  - Full target URL (shows site and API type)
-  - Request headers (non-sensitive: User-Agent, X-TD-Client, Content-Type, etc.)
-  - Response status and headers
-  - Sensitive headers (Authorization, Cookie, etc.) are hidden for security
-
-**Verbose Output Example:**
-```
-> POST https://api.treasuredata.com/v3/job/issue/hive/mydb
-> User-Agent: tdx/1.0.0 (darwin; node/24.0.0)
-> X-TD-Client: tdx
-> X-TD-Client-Version: 1.0.0
-> Content-Type: application/json
->
-
-< HTTP/1.1 200
-< content-type: application/json
-< x-td-request-id: abc123
-
-{"job_id": "12345"}
-```
-
 ### Database Commands
 
 | Command | Description | Example |
@@ -910,6 +923,178 @@ NO_COLOR=1 tdx databases
 3. `NO_COLOR` environment variable
 4. TTY detection (automatic)
 
+## Advanced Commands
+
+### API Command (Raw HTTP Access)
+
+Make authenticated HTTP requests to any Treasure Data API endpoint (similar to `gh api` from GitHub CLI).
+
+**Usage:** `tdx api <endpoint> [options]`
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `<endpoint>` | API endpoint path (must start with /) | `/v3/database/list` |
+| `-X, --method <method>` | HTTP method (GET, POST, PUT, DELETE, PATCH) | `-X POST` |
+| `--data <json>` | Request body as JSON string | `--data '{"name":"mydb"}'` |
+| `-f, --file <path>` | Read request body from file | `-f body.json` |
+| `-H, --header <header>` | Custom header (repeatable) | `-H "X-Custom: value"` |
+| `--type <api_type>` | API type (td, cdp, workflow, trino, llm) | `--type cdp` |
+
+**Examples:**
+
+```bash
+# GET request to TD API (default)
+tdx api /v3/database/list
+
+# GET with path parameters
+tdx api /v3/database/show/mydb
+tdx api /v3/table/list/mydb
+tdx api /v3/table/show/mydb/users
+
+# POST with inline JSON body (submit query)
+tdx api -X POST --data '{"query":"SELECT 1"}' /v3/job/issue/hive/mydb
+
+# POST with data from file
+tdx api -X POST -f query.json /v3/job/issue/hive/mydb
+
+# Custom headers
+tdx api -H "X-Custom: value" -H "X-Another: test" /v3/database/list
+
+# CDP API endpoints (read-only)
+tdx api /entities/parent_segments --type cdp
+tdx api /audiences/12345/segments --type cdp
+tdx api -X POST --data '{"format":"sql"}' /audiences/12345/segments/query --type cdp
+
+# Workflow API endpoints (read-only)
+tdx api /api/workflows --type workflow
+tdx api /api/projects --type workflow
+tdx api /api/attempts --type workflow
+
+# Trino API endpoints (query submission - plain SQL, not JSON)
+tdx api -X POST --data 'SELECT 1' /v1/statement --type trino
+
+# LLM API endpoints (read-only)
+tdx api /v1/agents --type llm
+tdx api /v1/models --type llm
+
+# Show HTTP response headers (with --verbose)
+tdx api /v3/database/list --verbose
+
+# Save output to file
+tdx api /v3/database/list --output databases.json
+
+# Combine --verbose with --output to see headers while saving
+tdx api /v3/database/list --verbose --output databases.json
+```
+
+**API Types:**
+
+| Type | Base URL Pattern | Description |
+|------|-----------------|-------------|
+| `td` | `api.treasuredata.com` | TD REST API (databases, tables, jobs) |
+| `cdp` | `api-cdp.treasuredata.com` | CDP API (audiences, segments, activations) |
+| `workflow` | `api-workflow.treasuredata.com` | Workflow API (digdag) |
+| `trino` | `api-presto.treasuredata.com` | Trino Query Engine API |
+| `llm` | `llm-api.treasuredata.com` | LLM API (agents, chat) |
+
+**Notes:**
+- All requests are automatically authenticated using your configured API key
+- Request body from `--data` must be valid JSON
+- `--data` and `--file` are mutually exclusive
+- Custom headers override default authentication headers
+- Response is output to stdout as JSON
+- Use `--verbose` to show HTTP request/response details in stderr:
+  - Full target URL (shows site and API type)
+  - Request headers (non-sensitive: User-Agent, X-TD-Client, Content-Type, etc.)
+  - Response status and headers
+  - Sensitive headers (Authorization, Cookie, etc.) are hidden for security
+
+**Verbose Output Example:**
+```
+> POST https://api.treasuredata.com/v3/job/issue/hive/mydb
+> User-Agent: tdx/1.0.0 (darwin; node/24.0.0)
+> X-TD-Client: tdx
+> X-TD-Client-Version: 1.0.0
+> Content-Type: application/json
+>
+
+< HTTP/1.1 200
+< content-type: application/json
+< x-td-request-id: abc123
+
+{"job_id": "12345"}
+```
+
+## Advanced Options
+
+### 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:
+
+**Usage:** `tdx --session <session-id> [command]`
+
+**Examples:**
+
+```bash
+# Process 1: Set session with explicit ID
+tdx --session my-workflow use database analytics
+tdx --session my-workflow use llm_project DataPipeline
+
+# Process 2: Reuse the same session
+tdx --session my-workflow context
+# Shows: Database: analytics, LLM Project: DataPipeline
+
+# Process 2: Run commands with shared context
+tdx --session my-workflow tables
+# Uses database: analytics
+
+# Clean up when done
+tdx --session my-workflow use --clear
+```
+
+**Use Cases:**
+- Sharing context between multiple terminal windows
+- Maintaining consistent context in CI/CD pipelines
+- Scripting scenarios where session persistence is needed
+
+**Note:** The `--session` option must be specified before the command name (e.g., `tdx --session id tables`, not `tdx tables --session id`).
+
+## Architecture
+
+The `tdx` project is designed with a layered architecture that separates the CLI interface from the core SDK, allowing the TypeScript SDK to be used in multiple environments:
+
+```mermaid
+graph TD
+    subgraph "Client Environments"
+        NodeJS[Node.JS/CLI<br/>tdx commands]
+        Browser[Web Browser<br/>Client-side]
+    end
+
+    subgraph "TDX SDK - TypeScript"
+        SDK[TDX SDK<br/>TypeScript/JavaScript API]
+    end
+
+    subgraph "Treasure Data APIs"
+        TD[TD REST API<br/>Databases, Tables, Jobs]
+        Trino[Trino Streaming API<br/>Query Execution]
+        CDP[CDP API<br/>Segments, Activations]
+    end
+
+    NodeJS --> SDK
+    Browser --> SDK
+
+    SDK -->|HTTPS| TD
+    SDK -->|HTTPS| Trino
+    SDK -->|HTTPS| CDP
+
+    style NodeJS fill:#d4f1d4
+    style Browser fill:#ffd4d4
+    style SDK fill:#fff5cc
+    style TD fill:#e8e8f0
+    style CDP fill:#e8e8f0
+    style Trino fill:#e8e8f0
+```
+
 ## TDX SDK
 
 **Usage Examples:**