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

### Using nvm (recommended for version management)


```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

### Using nvm (recommended)


```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


### Option A: PowerShell (Recommended)

#### Step 1: Install Node.js

Download and install Node.js from [nodejs.org](https://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](https://learn.microsoft.com/en-us/windows/wsl/).

#### 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](https://bun.sh/) 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

- [Profile Management](/treasure-code/guide/profile-management) — Set up multiple profiles for different environments
- [Proxy Configuration](/treasure-code/guide/proxy) — Configure an HTTP proxy for corporate networks
- [Commands Reference](/treasure-code/commands) — Explore all available commands