tdx

Appearance

Installation ​

This guide covers installing tdx on all platforms.

Requirements ​

  • Node.js 22.0.0 or higher (Node.js 24 Active LTS recommended)
  • TD API key with appropriate permissions

Quick Install ​

If you already have Node.js installed:

bash
npm install -g @treasuredata/tdx

macOS ​

Using Homebrew ​

bash
# Install Node.js
brew install node

# Install tdx
npm install -g @treasuredata/tdx
bash
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# Load nvm
\. "$HOME/.nvm/nvm.sh"

# Install Node.js 24
nvm install 24

# Install tdx
npm install -g @treasuredata/tdx

Linux ​

bash
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# Load nvm
\. "$HOME/.nvm/nvm.sh"

# Install Node.js 24
nvm install 24

# Install tdx
npm install -g @treasuredata/tdx

Secret Manager (for credential storage) ​

tdx stores API keys securely using your system's secret manager. Install libsecret:

bash
# Ubuntu/Debian
sudo apt update
sudo apt install -y libsecret-1-0 gnome-keyring

# Fedora/RHEL
sudo dnf install libsecret gnome-keyring

Windows ​

tdx works natively on Windows with PowerShell and Node.js. Choose the option that best fits your workflow:

  • PowerShell — Native Windows experience, recommended for most users
  • WSL2 — Linux environment within Windows, useful if you prefer bash/zsh

Step 1: Install Node.js ​

Download and install Node.js from nodejs.org, or use Windows Package Manager:

powershell
# Using winget (Windows 10/11)
winget install OpenJS.NodeJS.LTS

# Verify installation
node -v   # Should print v22.x.x or higher
npm -v    # Should print 10.x.x or higher

Step 2: Install tdx ​

powershell
npm install -g @treasuredata/tdx

# Verify installation
tdx --version

Credential Storage

Windows uses the built-in Credential Manager for secure API key storage. No additional setup required.

Option B: WSL2 (Alternative) ​

WSL2 provides a full Linux environment within Windows. This is useful if you:

  • Prefer bash/zsh over PowerShell
  • Want an environment matching Linux production servers
  • Work with Linux-specific tooling

Step 1: Install WSL2 ​

Open PowerShell as Administrator and run:

powershell
wsl --install

This installs WSL2 with Ubuntu as the default distribution. Restart your computer when prompted.

After restart, Ubuntu will launch automatically to complete setup. Create a username and password when prompted.

For more details, see the official WSL documentation.

Step 2: Install Node.js (using nvm) ​

Open your WSL terminal (Ubuntu) and run:

bash
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# Load nvm
\. "$HOME/.nvm/nvm.sh"

# Install Node.js 24
nvm install 24

# Verify installation
node -v  # Should print v22.x.x or higher
npm -v   # Should print 10.x.x or higher

Step 3: Install Secret Manager ​

bash
sudo apt update
sudo apt install -y libsecret-1-0 libsecret-1-dev gnome-keyring dbus-x11

To initialize the keyring:

bash
# Start D-Bus if not running
eval $(dbus-launch --sh-syntax)

# Initialize keyring (you'll be prompted for a password)
gnome-keyring-daemon --unlock

Step 4: Install tdx ​

bash
npm install -g @treasuredata/tdx

Verify Installation ​

bash
tdx --version

Set Up Authentication ​

Run the interactive setup:

bash
tdx auth setup

This will prompt you for:

  1. Region — Where your Treasure Data account lives (US, JP, EU, or AP)
  2. API Key — Your personal API key from Treasure Data

Verify your setup with:

bash
tdx status

This shows your authentication status, user info, current context, and configuration files all in one view.

Install Claude Code (Optional) ​

To use AI-powered development:

bash
npm install -g @anthropic-ai/claude-code

Launch Claude Code with Treasure Data skills:

bash
tdx claude

Alternative: Using Bun ​

Bun is a fast JavaScript runtime that works as a drop-in replacement:

bash
# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

# Install tdx
bun install -g @treasuredata/tdx

Troubleshooting ​

"Command not found: tdx" ​

The npm global bin folder might not be in your PATH.

macOS/Linux:

bash
# Add to ~/.bashrc or ~/.zshrc
export PATH="$PATH:$(npm config get prefix)/bin"

# Reload your shell
source ~/.bashrc

Windows (PowerShell):

powershell
# Check if npm global bin is in PATH
npm config get prefix

# The bin folder should be at: C:\Users\<username>\AppData\Roaming\npm
# If tdx still isn't found, restart your terminal or re-login

Keychain errors on Linux/WSL2 ​

If you see errors about the keychain being unavailable:

  1. Ensure libsecret is installed:

    bash
    sudo apt install -y libsecret-1-0 gnome-keyring

  2. Start the D-Bus daemon:

    bash
    eval $(dbus-launch --sh-syntax)

  3. As a fallback, use environment variables:

    bash
    export TDX_API_KEY=your-api-key-here

WSL2 network issues ​

If you have trouble connecting to Treasure Data APIs from WSL2:

bash
# Check your DNS settings
cat /etc/resolv.conf

# If needed, override DNS
sudo sh -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'

Windows: Execution policy errors ​

If you see "running scripts is disabled on this system":

powershell
# Run PowerShell as Administrator and execute:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Next Steps ​

Copyright 2024-present Treasure Data