@treasuredata/tdx 0.3.0 → 0.3.2

package/README.md

@@ -1,1728 +1,66 @@
 # tdx - AI-Native CLI for Treasure Data
 
-> **Status:** 🚧 Under Active Development. SDK/CLI commands are subject to change (2025)
+> **Status:** Under Active Development. SDK/CLI commands are subject to change (2025)
 
 A modern, AI-native command-line interface for Treasure Data, optimized for both human engineers and AI coding assistants.
 
+**Documentation:** [https://tdx.treasuredata.com/](https://tdx.treasuredata.com/)
+
 ## Features
 
-- 🤖 **AI-Native Design**: Consistent JSON output, predictable error codes, structured responses
-- 🌍 **Multi-Site Support**: Easy switching between US, JP, EU, and AP regions
-- 🚀 **Modern Distribution**: Install via `npx` or `npm` without prior setup
-- ⚡ **Fast & Efficient**: Built with TypeScript on Node.js 24+
+- **AI-Native Design**: Consistent JSON output, predictable error codes, structured responses
+- **Claude Code Integration**: Launch Claude Code with TD LLM API using `tdx claude`
+- **Multi-Site Support**: Easy switching between US, JP, EU, and AP regions
+- **Modern Distribution**: Install via `npx` or `npm` without prior setup
 
 ## Installation
 
 ```bash
-# Run directly with npx (no installation required)
-npx @treasuredata/tdx databases
-
-# Run latest version with npx
-npx @treasuredata/tdx@latest databases
-
-# Or install globally
+# Install globally
 npm install -g @treasuredata/tdx
 
-# Alternative: Use with Bun
-bunx @treasuredata/tdx databases
-
-# Run latest version with bunx
-bunx @treasuredata/tdx@latest databases
+# Or run directly with npx (no installation required)
+npx @treasuredata/tdx databases
 ```
 
 ## Quick Start
 
-### 1. Set Up Authentication
-
-**Recommended: Use the interactive setup command**
-
 ```bash
-# Interactive setup with site selection
+# Set up authentication (interactive)
 tdx auth setup
 
-# Or specify site directly
-tdx auth setup --site jp01
-
-# Set up profile-specific authentication
-tdx auth setup --profile work --site eu01
-```
-
-The setup command will:
-- Guide you through site selection
-- Securely prompt for your API key (hidden input)
-- Validate the API key before saving
-- Save to `~/.config/tdx/.env` (or `.env.{profile}` for profiles)
-
-**Alternative: Manual configuration**
-
-Create `~/.config/tdx/.env`:
-```bash
-TD_API_KEY=your-api-key-here/...
-```
-
-Or set as environment variable:
-```bash
-export TD_API_KEY=your-api-key-here/...
-```
-
-**Check authentication status:**
-```bash
-tdx auth
-```
-
-### 2. Run Commands
-
-```bash
 # List databases
 tdx databases
 
-# List databases in Tokyo region
-tdx databases --site jp01
-
-# Show table contents
-tdx show sample_datasets.www_access --limit 10
-
 # Run a query
-tdx query "SELECT * FROM mytable LIMIT 10"
-
-# Get JSON output (two ways)
-tdx databases --json
-tdx databases --format json
-
-# Get JSON Lines output
-tdx query "SELECT * FROM users" --jsonl
+tdx query "SELECT * FROM mydb.users LIMIT 10"
 
-# Get TSV output
-tdx query "SELECT * FROM users" --tsv
-
-# Get human-readable table output (default)
-tdx databases --format table
-
-# Chat with AI (simplified - uses default agent)
+# Chat with AI
 tdx chat "Show me customer revenue trends"
 
-# 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
-
-```bash
-tdx <command> [options] [arguments]
-```
-
-### Global Options
-
-Available for all commands:
-
-- `--site <site>`: TD site/region (us01, jp01, eu01, ap02) - default: us01
-- `--format <format>`: Output format (table, json, jsonl, tsv) - default: table
-- `--json`: Output in JSON format (shorthand for --format json)
-- `--jsonl`: Output in JSON Lines format (shorthand for --format jsonl)
-- `--tsv`: Output in TSV format (shorthand for --format tsv)
-- `--output <file>`: Save output to file
-- `--limit <rows>`: Maximum rows to display in table format - default: 40
-- `--color`: Force ANSI color output (overrides TTY detection)
-- `--no-color`: Disable ANSI color output (also respects NO_COLOR env var)
-- `-v, --verbose`: Enable verbose logging
-- `--timeout <seconds>`: Set operation timeout - default: 30
-- `--dry-run`: Preview operation without executing
-- `-y, --yes`: Skip confirmation prompts
-
-**Note:** Shorthand flags (--json, --jsonl, --tsv) are only applied when --format is not explicitly specified. If both are provided, --format is used.
-
-### Interactive Table Navigation
-
-When viewing table output in an interactive terminal, `tdx` automatically pipes the output through `less` for easy navigation of large datasets. This allows you to:
-
-- View all rows without truncation (unlimited data display)
-- Scroll through wide tables without column truncation
-- Search and navigate efficiently
-
-**Keyboard shortcuts in less:**
-
-| Key | Action |
-|-----|--------|
-| `q` | Quit and return to terminal |
-| `↑` / `↓` | Scroll up/down one line |
-| `Space` / `Page Down` | Scroll down one page |
-| `b` / `Page Up` | Scroll up one page |
-| `←` / `→` | Scroll left/right (for wide tables) |
-| `/pattern` | Search forward for pattern |
-| `?pattern` | Search backward for pattern |
-| `n` | Repeat previous search forward |
-| `N` | Repeat previous search backward |
-| `g` | Go to first line |
-| `G` | Go to last line |
-| `h` | Show help |
-
-**Note:** Less pagination is automatically enabled for table format output in interactive terminals. It's disabled when:
-- Output is piped to another command
-- Output is saved to a file with `--output`
-- Using non-table formats (JSON, JSONL, TSV)
-
-### Auth Commands
-
-Set up and manage authentication for Treasure Data.
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `auth setup` | Interactive API key setup (recommended) | `tdx auth setup` |
-| `auth setup --site <site>` | Setup for specific site | `tdx auth setup --site jp01` |
-| `auth setup --profile <name>` | Setup profile-specific auth | `tdx auth setup --profile work` |
-| `auth` | Check authentication status and validate | `tdx auth` |
-
-**Examples:**
-```bash
-# Interactive setup (recommended)
-tdx auth setup
-
-# Setup for Japan site
-tdx auth setup --site jp01
-
-# Setup work profile with EU site
-tdx auth setup --profile work --site eu01
-
-# Check authentication status
-tdx auth
-
-# Check status for specific site
-tdx auth --site jp01
-```
-
-**What `tdx auth setup` does:**
-- Guides you through site selection (arrow keys navigation)
-- Securely prompts for API key (hidden input with password masking)
-- **Validates API key** before saving (prevents invalid keys)
-- Saves to `~/.config/tdx/.env` or `.env.{profile}` for profiles
-- Registers profile metadata in `tdx.json` (when using `--profile`)
-- ESC or Ctrl+C to cancel anytime
-
-**Features:**
-- 🔒 Secure password-masked input
-- ✅ API key validation before saving
-- 🎯 Arrow key navigation for site selection
-- ⚡ Pre-selects site from `--site` flag
-- 📋 Profile support with metadata tracking
-
-### Chat Commands (Quick AI Interaction)
-
-Simplified top-level command for chatting with LLM agents.
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `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 or alias (haiku, sonnet) | `tdx chat "Help" --model "haiku"` |
-| `chat <message> --temperature <n>` | Set temperature (0.0-2.0, default: 0.7) | `tdx chat "Be creative" --temperature 1.2` |
-| `chat <message> --new` | Start a new chat session | `tdx chat --new "Fresh conversation"` |
-
-**Examples**:
-```bash
-# Simple chat (uses default agent with claude-4.5-haiku)
-tdx chat "Show me the top customers by revenue"
-
-# Continue previous conversation (default behavior)
-tdx chat "What about last quarter?"
-
-# Start a new conversation
-tdx chat --new "Tell me about data modeling best practices"
-
-# Use model aliases for quick access
-tdx chat "Quick question" --model "haiku"     # Uses claude-4.5-haiku
-tdx chat "Analyze this" --model "sonnet"      # Uses claude-4.5-sonnet
-
-# Use full model name
-tdx chat "Help me write SQL" --model "claude-4.5-opus"
-
-# Use specific agent by name (uses current project context)
-tdx llm use "MyProject"
-tdx chat "Analyze churn" --agent "Data Analyst"
-
-# 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**: Continues last chat session automatically
-- **Session persistence**: Last chat ID saved to `.cache/tdx/last_chat_id`
-- **--new flag**: Starts a fresh chat session
-- **--agent**: Use specific agent by name (resolves using project context)
-- **--model**: Auto-creates/reuses agent per model (supports aliases: `haiku` → `claude-4.5-haiku`, `sonnet` → `claude-4.5-sonnet`)
-- **--temperature**: Controls randomness (0.7 default, lower=focused, higher=creative)
-
-### Database Commands
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `databases` | List all databases | `tdx databases` |
-| | Filter by pattern (glob/wildcards) | `tdx databases "prod_*"` or `tdx databases "*_analytics"` |
-
-### Table Commands
-
-All table commands use dot-separated patterns: `(database).(table)`
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `tables` | List all tables from all databases | `tdx tables` |
-| | List all tables from specific database | `tdx tables "mydb.*"` or `tdx tables --in mydb` |
-| | List tables from database (--database flag) | `tdx tables --database mydb` |
-| | Filter tables with pattern | `tdx tables "mydb.user_*"` |
-| | Database pattern with table | `tdx tables "prod_*.access_log"` |
-| | Wildcard database and table | `tdx tables "*.user*"` |
-| | All tables from all databases | `tdx tables "*.*"` |
-| `describe <table>` (alias: `desc`) | Show table schema | `tdx describe mydb.users` |
-| | Using --in or --database flag | `tdx describe users --in mydb` or `tdx describe users -d mydb` |
-| `show <table>` | Show table contents (SELECT * with limit) | `tdx show mydb.users` |
-| | With custom row limit | `tdx show mydb.users --limit 10` |
-| | With explicit catalog | `tdx show td.mydb.users --limit 5` |
-| | Using --in or --database flag | `tdx show users --in mydb` or `tdx show users -d mydb` |
-
-**Pattern syntax:**
-- Database wildcard: `"mydb.*"` → all tables from mydb (use this or `--database mydb`)
-- Database.table: `mydb.users` → specific table
-- Wildcards: `"*.users"`, `"prod_*.user*"` → pattern matching
-- Catalog: `"td.mydb.users"` → with catalog prefix
-
-**Table-specific options:**
-- `-d, --database <database>`: Specify database name when not included in pattern
-- `--in <database>`: Alias for `--database` (natural language style)
-
-**Alternative syntax for specifying database:**
-
-There are multiple ways to specify the database for table commands:
-
-```bash
-# Using dot notation (recommended for patterns)
-tdx tables "mydb.*"
-
-# Using --in flag (natural language style, no quotes needed)
-tdx tables --in mydb
-
-# Using --database flag (or -d shorthand)
-tdx tables --database mydb
-tdx tables -d mydb
-
-# All three are equivalent for listing all tables from a database
-
-# Works with describe and show commands too
-tdx describe users --in mydb
-tdx show users --in mydb
-
-# List tables matching pattern from "mydb"
-tdx tables "user*" --in mydb
-```
-
-**Note:** If the pattern already includes a database (e.g., `mydb.users`), the `--database` option is ignored:
-
-```bash
-# Uses "mydb" from pattern, ignores --database option
-tdx tables mydb.users --database other
-# Result: Lists users table from mydb, not other
-```
-
-### Query Commands
-
-Usage: `tdx query [options] [sql]`
-
-| Option/Usage | Description | Example |
-|--------------|-------------|---------|
-| `<sql>` | Execute SQL query | `tdx query "SELECT * FROM table"` |
-| `-f, --file <path>` | Execute SQL from file | `tdx query -f query.sql` |
-| Multi-statement | Execute multiple statements (CLI or file) | `tdx query "SELECT 1; SELECT 2"` |
-| | Multi-statement from file | `tdx query -f setup-and-query.sql` |
-
-**Query-specific options**:
-- `-f, --file <path>`: Read SQL from file
-- `-d, --database <db>`: Database to query (default: information_schema)
-- `--in <db>`: Alias for `--database` (natural language style)
-- `--catalog <catalog>`: Trino catalog (default: td)
-
-**Examples**:
-```bash
-# Query with --in flag
-tdx query "SELECT * FROM users" --in mydb
-
-# Equivalent to --database
-tdx query "SELECT * FROM users" --database mydb
-tdx query "SELECT * FROM users" -d mydb
-```
-
-### Job Commands
-
-Manage and execute Treasure Data jobs (queries).
-
-**List jobs**:
-```bash
-# List jobs (default: 40 jobs)
-tdx jobs
-
-# List more jobs with --limit
-tdx jobs --limit 100
-
-# Filter by status
-tdx jobs --status running
-tdx jobs --status success
-tdx jobs --status error
-tdx jobs --status queued
-
-# Combine filters
-tdx jobs --status running --limit 50
-
-# Output as JSON
-tdx jobs --format json
-```
-
-**Show job details**:
-```bash
-# Show job details
-tdx job show <job-id>
-
-# Show job as JSON
-tdx job show <job-id> --format json
-```
-
-**Kill a job**:
-```bash
-# Kill a job (with confirmation)
-tdx job kill <job-id>
-
-# Skip confirmation prompt
-tdx job kill <job-id> --yes
-```
-
-**Submit jobs**:
-```bash
-# Submit Trino query (default)
-tdx job submit "SELECT * FROM mydb.table LIMIT 10"
-
-# Submit with specific database
-tdx job submit "SELECT * FROM table" --database mydb
-
-# Submit Hive query from file
-tdx job submit --job-type hive -f query.sql --database mydb
-
-# Submit without specifying database (uses information_schema by default)
-tdx job submit "SELECT 1"
-```
-
-**Get job results**:
-```bash
-# Get job results (table format)
-tdx job result <job-id>
-
-# Get results as JSON
-tdx job result <job-id> --format json
-
-# Save results to file
-tdx job result <job-id> --output results.json
-
-# Get results as TSV
-tdx job result <job-id> --format tsv
-```
-
-**Job Command Options**:
-- `--job-type <type>`: Job type - `trino` (default) or `hive`
-- `-f, --file <path>`: Read query from file
-- `--database <name>`: Database name (default: `information_schema`)
-- `--status <status>`: Filter by job status - `queued`, `running`, `success`, or `error` (for `jobs` list)
-- `--limit <number>`: Maximum number of jobs to list (default: 40, for `jobs` list)
-
-### Segment Commands (CDP)
-
-Usage: `tdx segment <subcommand> [options] [arguments]`
-
-CDP (Customer Data Platform) segment management for audiences and activations with file-system-like navigation.
-
-**Path Format:**
-- Parent segment: `"My Audience"`
-- Child segment: `"My Audience/High Value Users"`
-- Nested folders: `"My Audience/Marketing/Campaigns/Email Q1"`
-- Pattern matching: `"*DEMO"`, `"test*"`, `"*audience*"`
-- **Note**: Names are case-sensitive
-
-**Navigation Model:**
-- Set context: `tdx segment use <path>` - Navigate into a parent or folder
-- Show context: `tdx segment pwd` - Display current location
-- List contents: `tdx segments` - Show folders + segments in current context
-- All commands support both absolute paths and relative paths from context
-
-#### Navigation Commands
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `segment use <path>` | Set current context to parent or folder | `tdx segment use "My Audience/Marketing"` |
-| `segment pwd` | Show current context path | `tdx segment pwd` |
-| `segment use /` | Clear context (back to root) | `tdx segment use /` |
-| `segment use ..` | Navigate to parent folder | `tdx segment use ..` |
-
-#### Discovery Commands
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `segments` | List contents in current context (or all parents if no context) | `tdx segments` |
-| `segments <path>` | List folders + segments at specified path | `tdx segments "My Audience/Marketing"` |
-| `segments <pattern>` | List parents matching pattern (glob) | `tdx segments "*DEMO"` |
-| `segments -r` | List recursively (tree view) | `tdx segments -r` |
-| `segments <path> -r` | Recursive tree from path | `tdx segments "My Audience" -r` |
-| `segment describe <path>` | Show details (parent/folder/segment) | `tdx segment describe "My Audience/Marketing"` |
-| `segment show <path>` | Execute segment SQL query and show results | `tdx segment show "My Audience/Premium Users"` |
-| `segment sql <path>` | Get SQL query for segment | `tdx segment sql "My Audience/Marketing/Premium"` |
-| `segment fields <parent>` | List available fields for segmentation | `tdx segment fields "My Audience"` |
-
-#### Management Commands
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `segment parent create <name>` | Create new parent segment (audience) | `tdx segment parent create "Customer 360" --database mydb --table customers` |
-| `segment parent update <name>` | Update existing parent segment | `tdx segment parent update "Customer 360" --description "Updated"` |
-| `segment create <path>` | Create child segment with filtering (supports nested paths) | `tdx segment create "My Audience/Marketing/Premium" --rule-file rule.json` |
-| `segment update <path>` | Update child segment (supports nested paths) | `tdx segment update "My Audience/Marketing/Premium" --description "Updated"` |
-| `segment folder create <parent> <folder>` | Create segment folder | `tdx segment folder create "My Audience" "Q1 2024"` |
-
-#### Discovery Examples
-
-**Navigation Workflow:**
-
-```bash
-# List all parent segments
-tdx segments
-# Output:
-# [parent segments]
-# 👥 My Audience (50K)
-# 👥 Sales Leads (12.5K)
-
-# Pattern matching for parents
-tdx segments "*DEMO"
-# Output:
-# [parent segments]
-# 👥 TREASUREBIKES DEMO (3.28K)
-# 👥 TEST DEMO (1.5K)
-
-# Navigate into a parent
-tdx segment use "My Audience"
-
-# List folders + segments in current context (unified view)
-tdx segments
-# Output:
-# [/My Audience]
-# 📁 Marketing
-# 📁 Sales
-# 🎯 Active Users (35K)
-# 🎯 All Users (50K)
-
-# Recursive tree view from current context
-tdx segments -r
-# Output:
-# [/My Audience]
-# 📁 Marketing
-# ├── 📁 Campaigns
-# │   ├── 🎯 Email Q1 (5.23K)
-# │   └── 🎯 Email Q2 (6.12K)
-# └── 🎯 Email Subscribers (15K)
-# 🎯 Active Users (35K)
-
-# Navigate to nested folder
-tdx segment use "My Audience/Marketing/Campaigns"
-tdx segment pwd
-# Output: My Audience/Marketing/Campaigns
-
-# List specific path without changing context
-tdx segments "My Audience/Marketing"
-tdx segments "My Audience" -r  # Recursive from specific path
-
-# Show details using absolute paths
-tdx segment describe "My Audience/Marketing/Campaigns"
-tdx segment describe "My Audience/High Value Users"
-
-# Show details using relative paths (from context)
-tdx segment use "My Audience/Marketing"
-tdx segment describe "Campaigns"  # Relative to Marketing
-
-# Execute queries with paths
-tdx segment show "My Audience/Premium Users" --limit 100
-tdx segment sql "My Audience/Marketing/Email Subscribers" > query.sql
-
-# List available fields for parent
-tdx segment fields "My Audience"
-```
-
-#### Management Examples
-
-**Create Parent Segment (Audience):**
-
-```bash
-# Create minimal parent segment
-tdx segment parent create "Customer 360" \
-  --database customer_data \
-  --table customers \
-  --description "Complete customer view"
-
-# Create with attributes from file
-tdx segment parent create "Customer 360" \
-  --database customer_data \
-  --table customers \
-  --attributes-file examples/parent-segment-attributes.json \
-  --behaviors-file examples/parent-segment-behaviors.json
-
-# Create with scheduling
-tdx segment parent create "Customer 360" \
-  --database customer_data \
-  --table customers \
-  --schedule-type daily \
-  --schedule-option "03:00" \
-  --timezone "America/Los_Angeles"
-```
-
-**Update Parent Segment:**
-
-```bash
-# Update description
-tdx segment parent update "Customer 360" \
-  --description "Updated customer view"
-
-# Add new attributes
-tdx segment parent update "Customer 360" \
-  --add-attributes-file new-attributes.json
-
-# Update schedule
-tdx segment parent update "Customer 360" \
-  --schedule-type weekly \
-  --schedule-option "0"  # Sunday
-```
-
-**Create Child Segment with Filtering:**
-
-```bash
-# Create segment with simple rule (inline JSON)
-tdx segment create "My Audience/High Value" \
-  --description "Customers with LTV > $1000" \
-  --rule '{"type":"And","conditions":[{"type":"Value","leftValue":{"name":"Lifetime Value"},"operator":{"type":"Greater","rightValue":1000}}]}'
-
-# Create segment with complex rule (from file)
-tdx segment create "My Audience/High Value US" \
-  --description "High value US customers" \
-  --rule-file examples/segment-rule-complex.json
-
-# Create segment in folder
-tdx segment create "My Audience/Premium" \
-  --rule-file examples/segment-rule-simple.json \
-  --folder "Geographic Segments"
-
-# Create realtime segment
-tdx segment create "My Audience/Realtime Active" \
-  --rule-file rule.json \
-  --kind 1  # 0=batch, 1=realtime, 2=funnel_stage
-```
-
-**Update Child Segment:**
-
-```bash
-# Update segment name
-tdx segment update "My Audience/High Value" \
-  --name "Super High Value"
-
-# Update segment rule
-tdx segment update "My Audience/High Value" \
-  --description "Updated criteria" \
-  --rule-file updated-rule.json
-
-# Move segment to folder
-tdx segment update "My Audience/High Value" \
-  --folder "Premium Customers"
-```
-
-**Create Folders:**
-
-```bash
-# Create top-level folder
-tdx segment folder create "My Audience" "Q1 2024 Campaigns" \
-  --description "Campaign segments for Q1"
-
-# Create nested folder
-tdx segment folder create "My Audience" "West Region" \
-  --parent-folder "Geographic Segments"
+# Launch Claude Code with TD LLM
+tdx claude
 ```
 
-**Segment Rule Syntax:**
-
-See `examples/segment-rule-simple.json` and `examples/segment-rule-complex.json` for rule examples.
-
-Supported operators:
-- **Comparison**: Equal, NotEqual, Greater, GreaterEqual, Less, LessEqual
-- **Set**: In, NotIn
-- **Text**: Contains, StartsWith, EndsWith
-- **Pattern**: Regex
-- **Time**: TimeWithinPast
+## Documentation
 
-Example rule structure:
-```json
-{
-  "type": "And",
-  "conditions": [
-    {
-      "type": "Value",
-      "leftValue": {"name": "Lifetime Value"},
-      "operator": {"type": "Greater", "rightValue": 1000}
-    },
-    {
-      "type": "Value",
-      "leftValue": {"name": "Country"},
-      "operator": {"type": "In", "rightValues": ["US", "UK", "CA"]}
-    }
-  ]
-}
-```
+For detailed documentation, visit [https://tdx.treasuredata.com/](https://tdx.treasuredata.com/):
 
-### Activation Commands (CDP)
+- [Getting Started Guide](https://tdx.treasuredata.com/guide/)
+- [Authentication](https://tdx.treasuredata.com/guide/authentication)
+- [Commands Reference](https://tdx.treasuredata.com/commands/)
+- [Claude Code Integration](https://tdx.treasuredata.com/commands/claude)
+- [TD Skills for Claude Code](https://tdx.treasuredata.com/guide/td-skills)
 
-Manage CDP activations (syndications) for segments.
+## Requirements
 
-| Command | Description | Example |
-|---------|-------------|---------|
-| `activations <parent_name/child_name>` | List activations for a child segment | `tdx activations "My Audience/Premium Users"` |
+- **Node.js 22.0.0 or higher** (Node.js 24 Active LTS recommended)
+- TD API key with appropriate permissions
 
-**Examples**:
-```bash
-# List activations for a child segment (slash notation with names)
-tdx activations "My Audience/Premium Users"
+## License
 
-# Get activations as JSON
-tdx activations "My Audience/High Value Users" --format json
+Apache-2.0
 
-# Using Tokyo region
-tdx activations "My Audience/Premium Users" --site jp01
-```
-
-### Workflow Commands
-
-Usage: `tdx workflow <subcommand>` (alias: `tdx wf`)
-
-Manage Treasure Data workflows powered by Digdag. Monitor execution sessions, view logs, and control workflow attempts.
-
-| Subcommand | Description | Example |
-|------------|-------------|---------|
-| `projects [pattern]` | List workflow projects (supports glob patterns) | `tdx wf projects` or `tdx wf projects "cdp_*"` |
-| `workflows [project]` (alias: `ls`) | List workflows (filter by project, supports globs) | `tdx wf workflows` or `tdx wf workflows "lda*"` |
-| `sessions [project]` | List workflow execution sessions | `tdx wf sessions` or `tdx wf sessions myproject` or `tdx wf sessions myproject.daily_etl` |
-| `attempts [project]` | List workflow attempts | `tdx wf attempts` or `tdx wf attempts myproject` or `tdx wf attempts myproject.workflow` |
-| `attempt <attempt-id>` | Show specific attempt details | `tdx wf attempt 67890` |
-| `tasks <attempt-id>` | Show tasks for an attempt | `tdx wf tasks 67890` |
-| `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:**
-
-For `sessions` command:
-- `--status <status>`: Filter by status (running, success, error, blocked, all)
-- `--from <timestamp>`: Start time filter (ISO 8601 format)
-- `--to <timestamp>`: End time filter (ISO 8601 format)
-
-For `attempts` command:
-- `--include-retried`: Include retried attempts in the output
-
-For `tasks` command:
-- `--include-subtasks`: Include subtasks in the output
-
-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
-
-For `retry` command:
-- `--from-task <task>`: Resume from specific task (session retry only)
-- `--resume-from <task>`: Resume from specific task (attempt retry only)
-- `--params <json>`: Override parameters (JSON string or @file.json)
-- `--force`: Force retry even if not failed (attempt retry only)
-- `-y, --yes`: Skip confirmation prompt
-
-**Examples**:
-```bash
-# List all workflow projects
-tdx wf projects
-
-# Filter projects by pattern
-tdx wf projects "cdp_segment_*"
-
-# List all workflows
-tdx wf workflows
-
-# List workflows for a specific project
-tdx wf workflows myproject
-
-# Filter workflows by project pattern
-tdx wf workflows "lda*"
-
-# List all workflow sessions
-tdx wf sessions
-
-# List sessions for a specific project
-tdx wf sessions myproject
-
-# List sessions for specific workflow
-tdx wf sessions myproject.daily_etl
-
-# Filter sessions by status
-tdx wf sessions --status error
-
-# Filter sessions by time range
-tdx wf sessions --from "2025-01-01" --to "2025-01-31"
-
-# List all attempts
-tdx wf attempts
-
-# List attempts for a project
-tdx wf attempts myproject
-
-# List attempts for a workflow
-tdx wf attempts myproject.daily_etl
-
-# Include retried attempts
-tdx wf attempts --include-retried
-
-# Show specific attempt details
-tdx wf attempt 67890
-
-# Show tasks for an attempt
-tdx wf tasks 67890
-
-# Show tasks including subtasks
-tdx wf tasks 67890 --include-subtasks
-
-# View logs for a specific task
-tdx wf logs 67890 +step1
-
-# View logs with pagination
-tdx wf logs 67890 +step1 --offset 100 --limit 500
-
-# Kill a running attempt (with confirmation)
-tdx wf kill 67890
-
-# Kill with reason and skip confirmation
-tdx wf kill 67890 --reason "manual stop" -y
-
-# Retry entire session
-tdx wf retry session:12345
-
-# Retry session from specific task
-tdx wf retry session:12345 --from-task +step2
-
-# Retry attempt
-tdx wf retry attempt:67890
-
-# Retry attempt from specific task
-tdx wf retry attempt:67890 --resume-from +step2
-
-# Retry with parameter override
-tdx wf retry attempt:67890 --params '{"key":"value"}'
-
-# Retry with params from file
-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
-```
-
-### LLM Commands
-
-Usage: `tdx llm <subcommand>`
-
-Manage LLM projects, agents, and chat sessions with streaming support.
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `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` |
-| `llm proxy` | **[EXPERIMENTAL]** Start proxy server for Claude Code | `tdx llm proxy --port 4000` |
-| `claude` | Launch Claude Code with integrated LLM proxy | `tdx claude` |
-
-**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 or alias (default: claude-4.5-haiku)
-- `--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 `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 llm models
-
-# List all projects
-tdx llm projects
-
-# 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'
-
-# Create a new project
-tdx llm project create "MyProject" --description "My data analysis project"
-
-# Set current project context (session-only)
-tdx llm use "MyProject"
-
-# 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"
-
-# Override project with --llm-project option (highest priority)
-tdx llm agents --llm-project "OtherProject"
-tdx llm agent show "Agent" --llm-project "OtherProject"
-
-# 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
-
-# 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"
-
-# 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
-
-# Delete project
-tdx llm project delete "OldProject"
-
-# 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
-```
-
-### Claude Code Integration
-
-The `tdx claude` command provides seamless integration with Claude Code by automatically:
-1. Creating/using a default project and agent (or using cached haiku/sonnet/opus agent)
-2. Finding an available port and starting an LLM proxy server in the background
-3. Generating `.claude/settings.local.json` configuration file
-4. Launching Claude Code with the proxy configured
-5. Stopping the proxy server when Claude Code exits
-
-**Quick Start:**
-
-```bash
-# Launch Claude Code with default settings (uses haiku model)
-tdx claude
-
-# Use sonnet model instead
-tdx claude --model sonnet
-
-# Use opus model
-tdx claude --model opus
-
-# Enable debug/trace logging
-tdx --debug claude
-tdx --trace claude
-
-# Pass arbitrary options to Claude Code using '--' separator
-# Continue previous session
-tdx claude --model sonnet -- -c
-
-# Resume a specific session
-tdx claude -- -r session-id-here
-
-# Combine tdx and Claude Code options
-tdx claude --debug -- -c
-```
-
-**Requirements:**
-- Claude Code CLI must be installed (https://claude.com/claude-code)
-- The command will fail with a helpful error if Claude Code is not found
-
-**Debugging:**
-- Logs are written to `~/.cache/tdx/logs/proxy.log`
-- Use `--debug` for HTTP request/response logging
-- Use `--trace` for ultra-verbose internal operation logging
-- View logs in real-time: `tail -f ~/.cache/tdx/logs/proxy.log`
-
-**How It Works:**
-
-1. Creates or reuses a default agent (e.g., `tdx_claude-4.5-haiku`) with the specified model
-2. Finds an available port starting from 4000 (tries 4001, 4002, etc. if occupied)
-3. Starts `tdx llm proxy` in the background on the found port
-4. Creates `.claude/settings.local.json` with:
-   ```json
-   {
-     "env": {
-       "ANTHROPIC_BASE_URL": "http://127.0.0.1:4000",
-       "ANTHROPIC_MODEL": "haiku"
-     }
-   }
-   ```
-5. Launches Claude Code CLI
-6. When Claude Code exits, automatically stops the proxy server
-
-**Options:**
-
-- `--model <name>`: Model to use (haiku, sonnet, opus) - default: haiku
-- `--debug`: Enable debug mode (logs proxy request/response to stderr)
-
-**Model Selection:**
-
-The `--model` flag controls which TD agent is used:
-- `haiku` → Uses/creates `tdx_claude-4.5-haiku` agent (fast, cost-effective)
-- `sonnet` → Uses/creates `tdx_claude-4.5-sonnet` agent (balanced)
-- `opus` → Uses/creates `tdx_claude-opus` agent (most capable)
-
-All agents are created in your default project (`tdx_default_<username>`) and cached for reuse.
-
-**Advantages over Manual Setup:**
-- Zero configuration - just run `tdx claude` and start coding
-- Automatic port management - finds available port automatically
-- Automatic cleanup - stops proxy when Claude Code exits
-- Smart agent caching - reuses agents across sessions
-
-#### LLM Proxy Server for Claude Code
-
-> **⚠️ EXPERIMENTAL FEATURE**: This proxy server is experimental and may have limitations. Please report issues at https://github.com/treasure-data/tdx/issues
-
-The `tdx llm proxy` command starts a local HTTP server that provides Anthropic-compatible API endpoints, allowing Claude Code and other AI coding assistants to use Treasure Data's LLM API as a backend.
-
-**Starting the Proxy:**
-
-```bash
-# Start proxy with default settings (port 4000)
-tdx llm proxy
-
-# Specify custom port
-tdx llm proxy --port 8000
-
-# Use specific project and agent
-tdx llm proxy --project "MyProject" --agent "MyAgent"
-
-# Use context (set with 'tdx llm use')
-tdx llm use "MyProject/MyAgent"
-tdx llm proxy
-
-# Enable debug mode to see request/response JSON
-tdx llm proxy --debug
-```
-
-**Claude Code Configuration:**
-
-Create a `.claude/settings.local.json` file in your project directory:
-
-```json
-{
-  "env": {
-    "ANTHROPIC_BASE_URL": "http://127.0.0.1:4000",
-    "ANTHROPIC_MODEL": "sonnet"
-  }
-}
-```
-
-**Testing with Agent SDK:**
-
-You can also test the proxy using [Claude Agent SDK](https://docs.claude.com/en/docs/agent-sdk/typescript):
-
-```bash
-npm install @anthropic-ai/sdk
-```
-
-The SDK reads `.claude/settings.json` for `ANTHROPIC_BASE_URL` configuration.
-
-**How It Works:**
-
-1. The proxy translates Anthropic Messages API calls to TD LLM API format
-2. Maintains conversation state across multiple requests
-3. Streams responses in real-time using Server-Sent Events (SSE)
-4. Maps model names (sonnet/haiku/opus) to TD models
-5. Supports tool calls via prompt engineering (see Tool Support below)
-
-**Proxy Options:**
-
-- `--port <number>`: Port to run the server on (default: 4000)
-- `--project <name>`: LLM project name (uses context or default)
-- `--agent <name>`: Agent name (uses context or default)
-- `--debug`: Enable debug mode (logs request/response JSON to stderr)
-
-**Tool Support:**
-
-The proxy supports Anthropic-style tool calls via prompt engineering:
-
-1. **Tool Definition Injection**: Tool definitions from the Anthropic request are converted into clear instructions and prepended to the user message
-2. **JSON-based Tool Calls**: The LLM is instructed to output tool calls as JSON: `{"tool_use":{"id":"toolu_xxx","name":"tool_name","input":{...}}}`
-3. **Automatic Detection**: The proxy parses the response stream to detect tool call JSON and converts it to proper Anthropic SSE events
-4. **Tool Results**: When the client sends tool results back, they're formatted and included in the next message to the LLM
-
-This approach works around the architectural differences between TD's server-driven tool system and Anthropic's client-driven model.
-
-**Known Limitations:**
-
-- Tool calls rely on prompt engineering (LLM must output correct JSON format)
-- Non-streaming responses are not implemented
-- Image inputs are not supported
-- System prompt is prepended to first message only (not persisted in agent)
-- TD's built-in tools (knowledge base, functions) are not directly accessible
-
-## Advanced Query Features
-
-### File Input
-
-Read SQL queries from files using the `-f` or `--file` option:
-
-```bash
-# Execute SQL from file
-tdx query --file query.sql
-
-# Short form
-tdx query -f query.sql
-
-# With options
-tdx query -f query.sql --database mydb --format json --output results.json
-```
-
-### Multi-Statement Execution
-
-Execute multiple SQL statements sequentially by separating them with semicolons. This works for both command-line input and file input:
-
-**From command line**:
-```bash
-tdx query "SELECT COUNT(*) FROM users; SELECT COUNT(*) FROM orders"
-```
-
-**From file** (`setup-and-query.sql`):
-```sql
-CREATE TABLE temp_users AS SELECT * FROM users WHERE active = true;
-CREATE TABLE temp_orders AS SELECT * FROM orders WHERE user_id IN (SELECT id FROM temp_users);
-SELECT COUNT(*) as order_count FROM temp_orders;
-```
-
-```bash
-tdx query -f setup-and-query.sql
-```
-
-**Output behavior**:
-- Each statement executes sequentially with progress indication
-- **Console output**: All results displayed as they complete
-- **File output** (`--output results.txt`): All results appended to single file
-- **Fail-fast**: Execution stops on first error
-
-**Example output**:
-```
-✔ Statement 1/3 - Query completed: Processed 1,000 rows in 2.3s
-┌────────────┐
-│ user_count │
-├────────────┤
-│ 1000       │
-└────────────┘
-✔ Statement 2/3 - Query completed: Processed 5,000 rows in 3.1s
-┌─────────────┐
-│ order_count │
-├─────────────┤
-│ 5000        │
-└─────────────┘
-✔ Statement 3/3 - Query completed: Processed 1 rows in 0.5s
-┌─────────────┐
-│ order_count │
-├─────────────┤
-│ 5000        │
-└─────────────┘
-```
-
-**With `--output`** (file mode):
-```bash
-tdx query -f statements.sql --output results.txt
-```
-- Console shows only progress messages
-- All results written to `results.txt` (appended sequentially)
-- Message: "All results saved to results.txt"
-
-## Output Formats
-
-tdx supports multiple output formats for query results and command outputs:
-
-### Table Format (default)
-Human-readable ASCII table with column types and row counts:
-```bash
-tdx query "SELECT name, age FROM users LIMIT 2"
-```
-```
-┌───────┬─────┐
-│ name  │ age │
-│ string│ int │
-├───────┼─────┤
-│ Alice │  25 │
-│ Bob   │  30 │
-├───────┴─────┤
-│ 2 rows      │
-└─────────────┘
-```
-
-### JSON Format
-Readable JSON array with newlines (no metadata):
-```bash
-tdx query "SELECT name, age FROM users LIMIT 2" --format json
-```
-```json
-[
-  {"name":"Alice","age":25},
-  {"name":"Bob","age":30}
-]
-```
-
-Each object is compact (single line) but separated by newlines for readability.
-
-Perfect for piping to `jq`:
-```bash
-tdx query "SELECT * FROM users" --format json | jq '.[0]'
-tdx query "SELECT * FROM users" --format json | jq 'length'
-```
-
-### JSON Lines Format (jsonl)
-One JSON object per line - ideal for streaming and line-by-line processing:
-```bash
-tdx query "SELECT name, age FROM users LIMIT 2" --format jsonl
-```
-```
-{"name":"Alice","age":25}
-{"name":"Bob","age":30}
-```
-
-Process line by line:
-```bash
-tdx query "SELECT * FROM users" --format jsonl | while read line; do
-  echo "$line" | jq '.name'
-done
-```
-
-### TSV Format
-Tab-separated values with header row:
-```bash
-tdx query "SELECT name, age FROM users LIMIT 2" --format tsv
-```
-```
-name	age
-Alice	25
-Bob	30
-```
-
-### Color Output
-
-`tdx` automatically adds ANSI colors to output in interactive terminals to improve readability:
-
-**Table format:**
-- Table borders: Dark gray (dim)
-- Column headers: Plain text (no color)
-- Type row: Dim gray
-- Data values: Plain text (no color)
-
-**JSON format:**
-- Keys: Blue
-- Strings: Green
-- Numbers: Cyan
-- Booleans: Yellow
-- Null values: Dim
-
-**JSONL format:**
-- Same color scheme as JSON format
-- Compact one-line-per-object output with colors in interactive terminals
-
-**Automatic detection:**
-- Colors are enabled automatically when output is to an interactive terminal (TTY)
-- Colors are disabled automatically when:
-  - Output is piped to another command
-  - Output is saved to a file with `--output`
-- Respects the `NO_COLOR` environment variable (see https://no-color.org/)
-
-**Manual control:**
-```bash
-# Force colors on (even when piping or saving to file)
-tdx databases --color
-tdx databases --color --output results.txt
-
-# Disable colors (even in interactive terminal)
-tdx databases --no-color
-
-# Disable colors via environment variable
-NO_COLOR=1 tdx databases
-```
-
-**Priority order:**
-1. `--no-color` flag (highest priority)
-2. `--color` flag
-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:**
-
-**Node.js:**
-```typescript
-import { TDX, loadLocalSDKConfig } from '@treasuredata/tdx/sdk';
-
-// Load config from environment or pass API key directly
-const config = loadLocalSDKConfig({
-  site: 'us01',
-  apiKey: 'your_key_id/your_key_secret'  // Optional: omit to load from env
-});
-const tdx = new TDX(config);
-const result = await tdx.query('SELECT * FROM users');
-```
-
-**Web Browser:**
-```html
-<script type="module">
-  import { TDX } from 'https://unpkg.com/@treasuredata/tdx';
-  // Browser: Create config object directly (loadLocalSDKConfig requires file system)
-  const config = {
-    site: 'us01',
-    apiKey: 'your_key_id/your_key_secret',
-    verbose: false
-  };
-  const tdx = new TDX(config);
-  const result = await tdx.query('SELECT * FROM users');
-</script>
-```
-
-
-## Requirements
-
-- **Node.js 22.0.0 or higher** (Node.js 24 Active LTS recommended for development)
-- TD API key with appropriate permissions
-
-
-## License
-
-Apache-2.0
-
-## Contributing
+## Contributing
 
 This project is maintained by the Treasure Data DevAI Unit.
-