@treasuredata/tdx 0.1.4 → 0.1.6

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,171 @@ 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/tdx.json` or project `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
+
+# 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"
+    }
+  }
+}
+```
+
+**Profile Locations:**
+- **User-level**: `~/.config/tdx/tdx.json` - Shared across all projects
+- **Project-level**: `(project folder)/tdx.json` - Project-specific profiles
+
+**Credentials:**
+Store API keys separately from profiles:
+```
+~/.config/tdx/
+  ├── tdx.json              # User-level profiles
+  ├── .env.production       # Production credentials
+  └── .env.dev              # Development credentials
+```
+
+**Example credential file** (`~/.config/tdx/.env.production`):
+```
+TD_API_KEY=1234/abcdefg...
+```
+
+**Profile Precedence:**
+1. Project `tdx.json` profiles (local)
+2. User `~/.config/tdx/tdx.json` profiles (user-level)
+3. Directory-based profiles (deprecated)
+
+**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
+
+# 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. 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 context --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 (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 ✓
 ```
 
 ## Available Commands
@@ -181,145 +308,48 @@ 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> --agent <ref>` | Chat with specific agent | `tdx chat "Hello" --agent "Project/Agent"` |
+| `chat <message>` | Chat (continues last session by default) | `tdx chat "Analyze my data"` |
+| `chat <message> --agent <name>` | Chat with specific agent | `tdx chat "Hello" --agent "Data Analyst"` |
 | `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?"
 
-# Use specific agent
-tdx chat "Analyze churn" --agent "MyProject/Data Analyst"
+# Start a new conversation
+tdx chat --new "Tell me about data modeling best practices"
 
-# Use specific model (reuses agent per model)
+# Use specific model (auto-creates/reuses agent)
 tdx chat "Help me write SQL" --model "gpt-5"
 
-# Adjust temperature for more creative responses
-tdx chat "Write a poem" --temperature 1.5
+# Use specific agent by name (uses current project context)
+tdx llm use "MyProject"
+tdx chat "Analyze churn" --agent "Data Analyst"
 
-# Combine options
-tdx chat "Be precise" --model "claude-4-sonnet" --temperature 0.3
+# Override project for agent lookup
+tdx chat "Hello" --agent "Analyst" --llm-project "OtherProject"
+
+# Adjust temperature
+tdx chat "Write a poem" --temperature 1.5
 
 # Verbose mode shows chat session ID
 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
 - **Session persistence**: Last chat ID saved to `.cache/tdx/last_chat_id`
-- **--continue flag**: Resumes last chat automatically
-- **--agent**: Use specific agent (requires `"project/agent"` format)
-- **--model**: Reuses or creates agent per model (e.g., `tdx_gpt-5`)
+- **--new flag**: Starts a fresh chat session
+- **--agent**: Use specific agent by name (resolves using project context)
+- **--model**: Auto-creates/reuses 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 |
@@ -433,20 +463,20 @@ CDP (Customer Data Platform) segment management for audiences and activations.
 
 **Name Format Conventions:**
 - Parent segment: `parent_name` (e.g., `"My Audience"`)
-- Child segment: `parent_name.child_name` (e.g., `"My Audience.High Value Users"`) - uses dot notation
-- Folder: `parent_name.folder_name` (e.g., `"My Audience.Marketing"`)
-- Pattern: Commands accept `(parent_name)(.child_name)?` format
+- Child segment: `parent_name/child_name` (e.g., `"My Audience/High Value Users"`) - uses slash notation
+- Folder: `parent_name/folder_name` (e.g., `"My Audience/Marketing"`)
+- Pattern: Commands accept `(parent_name)(/child_name)?` format
 - **Note**: Names are case-sensitive
 
 | Command | Description | Example |
 |---------|-------------|---------|
 | `segments` | List all parent segments | `tdx segments` |
 | `segments <parent_name>` | List child segments under parent | `tdx segments "My Audience"` |
-| `segment describe <name>` (alias: `desc`) | Show parent or child segment details | `tdx segment describe "My Audience"` or `tdx segment desc "My Audience.Premium Users"` |
-| `segment show <name>` | Execute segment SQL query and show results | `tdx segment show "My Audience"` or `tdx segment show "My Audience.Premium Users" --limit 100` |
-| `segment sql <name>` | Get SQL query for segment | `tdx segment sql "My Audience"` or `tdx segment sql "My Audience.Premium Users"` |
+| `segment describe <name>` (alias: `desc`) | Show parent or child segment details | `tdx segment describe "My Audience"` or `tdx segment desc "My Audience/Premium Users"` |
+| `segment show <name>` | Execute segment SQL query and show results | `tdx segment show "My Audience"` or `tdx segment show "My Audience/Premium Users" --limit 100` |
+| `segment sql <name>` | Get SQL query for segment | `tdx segment sql "My Audience"` or `tdx segment sql "My Audience/Premium Users"` |
 | `segment folders <parent_name>` | List folders under parent | `tdx segment folders "My Audience"` |
-| `segment folder show <parent_name.folder_name>` | Show folder details | `tdx segment folder show "My Audience.Marketing"` |
+| `segment folder show <parent_name/folder_name>` | Show folder details | `tdx segment folder show "My Audience/Marketing"` |
 
 **Examples**:
 ```bash
@@ -461,14 +491,14 @@ tdx segment describe "My Audience"
 # or use the alias
 tdx segment desc "My Audience"
 
-# Show child segment metadata (dot notation)
-tdx segment describe "My Audience.High Value Users"
+# Show child segment metadata (slash notation)
+tdx segment describe "My Audience/High Value Users"
 
 # Execute parent segment query and show results (default: 40 rows)
 tdx segment show "My Audience"
 
-# Execute child segment query with custom limit (dot notation)
-tdx segment show "My Audience.Premium Users" --limit 100
+# Execute child segment query with custom limit (slash notation)
+tdx segment show "My Audience/Premium Users" --limit 100
 
 # Execute segment query and save as JSON
 tdx segment show "My Audience" --format json --output results.json
@@ -476,14 +506,14 @@ tdx segment show "My Audience" --format json --output results.json
 # Get SQL for parent segment
 tdx segment sql "My Audience" > parent-query.sql
 
-# Get SQL for child segment with filtering (dot notation)
-tdx segment sql "My Audience.High Value Users" > child-query.sql
+# Get SQL for child segment with filtering (slash notation)
+tdx segment sql "My Audience/High Value Users" > child-query.sql
 
 # List folders under parent
 tdx segment folders "My Audience"
 
-# Show folder details (parent.folder notation)
-tdx segment folder show "My Audience.Marketing"
+# Show folder details (parent/folder notation)
+tdx segment folder show "My Audience/Marketing"
 ```
 
 ### Activation Commands (CDP)
@@ -492,18 +522,18 @@ Manage CDP activations (syndications) for segments.
 
 | Command | Description | Example |
 |---------|-------------|---------|
-| `activations <parent_name.child_name>` | List activations for a child segment | `tdx activations "My Audience.Premium Users"` |
+| `activations <parent_name/child_name>` | List activations for a child segment | `tdx activations "My Audience/Premium Users"` |
 
 **Examples**:
 ```bash
-# List activations for a child segment (dot notation with names)
-tdx activations "My Audience.Premium Users"
+# List activations for a child segment (slash notation with names)
+tdx activations "My Audience/Premium Users"
 
 # Get activations as JSON
-tdx activations "My Audience.High Value Users" --format json
+tdx activations "My Audience/High Value Users" --format json
 
 # Using Tokyo region
-tdx activations "My Audience.Premium Users" --site jp01
+tdx activations "My Audience/Premium Users" --site jp01
 ```
 
 ### Workflow Commands
@@ -523,6 +553,9 @@ Manage Treasure Data workflows powered by Digdag. Monitor execution sessions, vi
 | `logs <attempt-id> <task-name>` | Show logs for a specific task | `tdx wf logs 67890 +step1` |
 | `kill <attempt-id>` | Kill a running attempt | `tdx wf kill 67890` |
 | `retry <session-id\|attempt-id>` | Retry a session or attempt | `tdx wf retry session:12345` or `tdx wf retry attempt:67890` |
+| `download <project-name> [output-dir]` | Download workflow project from TD console | `tdx wf download myproject` or `tdx wf download myproject ./workflows` |
+| `push [project-name-or-dir]` | Push workflow project to TD console (digdag-style) | `cd myproject && tdx wf push myproject` or `tdx wf push ./myproject` |
+| `delete <project-name-or-id>` | Delete workflow project from TD console | `tdx wf delete myproject` or `tdx wf delete 12345` |
 
 **Workflow-specific options:**
 
@@ -540,6 +573,14 @@ For `tasks` command:
 For `logs` command:
 - `--offset <number>`: Starting offset for logs (default: 0)
 
+For `download` command:
+- `--revision <revision>`: Download specific revision (default: latest)
+
+For `push` command:
+- `--name <name>`: Project name (default: directory name)
+- `--revision <revision>`: Revision name (default: timestamp)
+- `--skip-validation`: Skip validation of .dig files
+
 For `kill` command:
 - `--reason <text>`: Reason for killing the attempt
 - `-y, --yes`: Skip confirmation prompt
@@ -637,88 +678,149 @@ tdx wf retry attempt:67890 --params @params.json
 # Force retry without confirmation
 tdx wf retry attempt:67890 --force -y
 
+# Download workflow project
+tdx wf download myproject
+
+# Download to specific directory
+tdx wf download myproject ./workflows
+
+# Download specific revision
+tdx wf download myproject --revision v1.0.0
+
+# Push workflow project (digdag-style: cd into project directory first)
+cd myproject
+tdx wf push myproject
+
+# Push with custom revision
+cd myproject
+tdx wf push myproject --revision v1.0.0
+
+# Push from parent directory with path
+tdx wf push ./myproject
+
+# Push with --name override
+cd myproject
+tdx wf push myproject --name production_workflow
+
+# Push from current directory without specifying name
+cd myproject
+tdx wf push
+
+# Push without validation
+cd myproject
+tdx wf push myproject --skip-validation
+
+# Delete workflow project (with confirmation)
+tdx wf delete myproject
+
+# Delete by project ID
+tdx wf delete 12345
+
+# Delete without confirmation
+tdx wf delete myproject -y
+
 # Get workflow data as JSON
 tdx wf sessions --format json --output sessions.json
 ```
 
-### Agent Commands (LLM API)
+### LLM Commands
 
-Usage: `tdx agent <subcommand>` | `tdx agents`
+Usage: `tdx llm <subcommand>`
 
-Manage LLM agents and chat sessions with streaming support.
+Manage LLM projects, agents, and chat sessions with streaming support.
 
 | Command | Description | Example |
 |---------|-------------|---------|
-| `agent models` | List available LLM models | `tdx agent models` |
-| `agent projects` | List all projects | `tdx agent projects` |
-| `agents [project-name]` | List all agents (or filter by project) | `tdx agents` or `tdx agents "MyProject"` |
-| `agent get <project/agent>` | Get agent details | `tdx agent get "MyProject/Data Analyst"` |
-| `agent create <name>` | Create a new agent | `tdx agent create "My Agent" --project-id <id> --model <model>` |
-| `agent update <project/agent>` | Update an agent | `tdx agent update "MyProject/Agent" --name "New Name"` |
-| `agent remove <project/agent>` | Delete an agent | `tdx agent remove "MyProject/Agent"` |
-| `agent history [chat-id]` | List chat sessions or show messages | `tdx agent history` or `tdx agent history chat456` |
-
-**Agent Reference Format:**
-
-Agent commands require the full project-scoped format (since agent names are only unique within a project):
-- `"project-name/agent-name"` - Required format for agent operations
-
-**Agent Command Options:**
-
-For `create` command:
-- `--project-id <id>`: Project ID (required)
+| `llm use <project>` | Set current project context | `tdx llm use "MyProject"` |
+| `llm models` | List available LLM models | `tdx llm models` |
+| `llm projects [pattern]` | List all projects (with wildcard support) | `tdx llm projects` or `tdx llm projects "data*"` |
+| `llm project create <name>` | Create a new project | `tdx llm project create "MyProject"` |
+| `llm project delete <name>` | Delete a project | `tdx llm project delete "MyProject"` |
+| `llm agents [pattern]` | List agents in current project (with wildcard support) | `tdx llm agents` or `tdx llm agents "test*"` |
+| `llm agent show <name>` | Show agent details | `tdx llm agent show "Data Analyst"` |
+| `llm agent create <name>` | Create a new agent in current project | `tdx llm agent create "My Agent" --model <model>` |
+| `llm agent update <name>` | Update an agent | `tdx llm agent update "Agent" --name "New Name"` |
+| `llm agent delete <name>` | Delete an agent | `tdx llm agent delete "Agent"` |
+| `llm history [chat-id]` | List chat sessions or show messages | `tdx llm history` or `tdx llm history chat456` |
+
+**Project Resolution (Precedence Order):**
+
+Agent commands resolve projects in this order:
+1. `--llm-project` global option (highest priority)
+2. `tdx llm use <project>` context (session-only)
+3. Default project `tdx_default_<username>` (auto-created)
+
+**Command Options:**
+
+For `project create`:
+- `--description <text>`: Project description
+
+For `agent create`:
 - `--system-prompt <text>`: System prompt/instructions (default: empty)
 - `--model <name>`: Model type (default: claude-4.5-sonnet)
 - `--starter-message <text>`: Starter message for the agent
 - `--max-tool-iterations <n>`: Maximum tool iterations (default: 4)
 - `--temperature <n>`: Temperature 0.0-2.0 (default: 0.7)
 
-For `update` command:
+For `agent update`:
 - `--name <text>`: New agent name
 - `--prompt <text>`: New prompt/instructions
 - `--description <text>`: New description
 - `--starter-message <text>`: New starter message
 
-
 **Examples**:
 ```bash
 # List available models
-tdx agent models
+tdx llm models
 
 # List all projects
-tdx agent projects
+tdx llm projects
 
-# List all agents
-tdx agents
+# List projects matching pattern (wildcards: * = any chars, ? = single char)
+tdx llm projects "data*"     # Projects starting with 'data'
+tdx llm projects "*_prod"    # Projects ending with '_prod'
 
-# List agents for a specific project (by project name)
-tdx agents "MyProject"
+# Create a new project
+tdx llm project create "MyProject" --description "My data analysis project"
 
-# Get agent details (requires project/agent format)
-tdx agent get "MyProject/Data Analyst"
+# Set current project context (session-only)
+tdx llm use "MyProject"
 
-# Create a new agent
-tdx agent create "Data Analyst" \
-  --prompt "You are a helpful data analyst specialized in SQL and data visualization" \
-  --starter-message "Hello! I can help you analyze your data."
+# Now all agent commands use "MyProject" by default:
+tdx llm agents                               # List agents in MyProject
+tdx llm agents "test*"                       # Filter agents by pattern
+tdx llm agent show "Data Analyst"            # Show agent from MyProject
+tdx llm agent create "Analyst" --model gpt-5 # Create in MyProject
+tdx llm agent update "Analyst" --name "Senior Analyst"
+tdx llm agent delete "Analyst"
 
-# Update agent (requires project/agent format)
-tdx agent update "MyProject/Data Analyst" --name "Senior Data Analyst"
+# Override project with --llm-project option (highest priority)
+tdx llm agents --llm-project "OtherProject"
+tdx llm agent show "Agent" --llm-project "OtherProject"
 
-# Update agent prompt
-tdx agent update "MyProject/Data Analyst" --prompt "New instructions"
+# Use default project (tdx_default_<username>) - no setup needed
+tdx llm agents              # Uses tdx_default_leo if no context set
+tdx llm agent create "Bot"  # Creates in default project
 
-# Delete agent (requires project/agent format)
-tdx agent remove "MyProject/Data Analyst"
+# Complete workflow: Create custom agent and chat with it
+tdx llm use "MyProject"
+tdx llm agent create "SQL Expert" \
+  --system-prompt "You are an expert in SQL and data analysis. Help users write efficient queries." \
+  --model "claude-4.5-sonnet"
 
-# List recent chat sessions
-tdx agent history
+# Now chat with your custom agent
+tdx chat "Help me analyze customer churn" --agent "SQL Expert"
+tdx chat "Show me the query for that"  # Continues conversation
 
-# Show specific chat message history
-tdx agent history chat456
+# Delete project
+tdx llm project delete "OldProject"
 
-# Get agents as JSON
-tdx agents --format json --output agents.json
+# Chat history
+tdx llm history              # List recent chat sessions
+tdx llm history chat456      # Show specific chat messages
+
+# JSON output
+tdx llm agents --format json --output agents.json
 ```
 
 ## Advanced Query Features
@@ -910,6 +1012,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:**