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:

npm install -g @treasuredata/tdx

macOS

Using Homebrew

# Install Node.js
brew install node

# Install tdx
npm install -g @treasuredata/tdx

Using nvm (recommended for version management)

# 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

Using nvm (recommended)

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

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

# Fedora/RHEL
sudo dnf install libsecret gnome-keyring

Windows (WSL2 Recommended)

For the best experience with tdx and Claude Code on Windows, we recommend using Windows Subsystem for Linux 2 (WSL2).

Why WSL2?

While tdx works on PowerShell, WSL2 offers:

• Better compatibility with Node.js tooling
• Native Linux environment matching production servers
• Full support for Claude Code and AI development workflows
• Easier setup for system keychain (credential storage)

Step 1: Install WSL2

Open PowerShell as Administrator and run:

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:

# 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 v24.x.x
npm -v   # Should print 11.x.x

Step 3: Install Secret Manager

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

To initialize the keyring:

# 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

npm install -g @treasuredata/tdx

Verify Installation

tdx --version

Set Up Authentication

Run the interactive setup:

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 it works:

tdx database list

Install Claude Code (Optional)

To use AI-powered development:

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

Launch Claude Code with Treasure Data skills:

tdx claude

Alternative: Using Bun

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

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

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

# Reload your shell
source ~/.bashrc

Keychain errors on Linux/WSL2

If you see errors about the keychain being unavailable:

1. Ensure libsecret is installed:

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

2. Start the D-Bus daemon:

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

3. As a fallback, use environment variables:

   export TDX_API_KEY=your-api-key-here

WSL2 network issues

If you have trouble connecting to Treasure Data APIs:

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

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

Next Steps

• Profile Management — Set up multiple profiles for different environments
• Commands Reference — Explore all available commands