> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the HopX CLI on Linux, macOS, or Windows. Multiple installation methods including quick install script, uv, pipx, and pip. Includes verification steps and troubleshooting.

Install the HopX CLI to manage cloud sandboxes from your terminal. The CLI supports multiple installation methods and works on Linux, macOS, and Windows (including WSL).

## Prerequisites

* **Python 3.12+** - Required for CLI operation
* **Terminal access** - Command-line interface
* **Internet connection** - For installation and API access

## Quick Install (Recommended)

The quick install script handles everything automatically, including PEP 668 environments on macOS/modern Linux:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/hopx-ai/hopx/main/cli/scripts/install.sh | bash
```

This script:

* Detects your platform (Linux, macOS, Windows/WSL)
* Installs the CLI using the best method for your system
* Adds the CLI to your PATH
* Verifies the installation

**Expected Output:**

```
✓ HopX CLI installed successfully
✓ Version: 0.1.2
✓ Run 'hopx init' to get started
```

## Alternative Installation Methods

### uv (Fastest)

[uv](https://github.com/astral-sh/uv) is a fast Python package installer:

```bash theme={null}
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install HopX CLI
uv tool install hopx-cli

# Verify installation
hopx --version
```

### pipx (Isolated)

[pipx](https://github.com/pypa/pipx) installs Python applications in isolated environments:

```bash theme={null}
# Install pipx (if not installed)
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install HopX CLI
pipx install hopx-cli

# Verify installation
hopx --version
```

### pip (User Install)

Install directly with pip:

```bash theme={null}
# Install for current user
pip install --user hopx-cli

# Add to PATH (if needed)
export PATH="$PATH:$(python3 -m site --user-base)/bin"

# Verify installation
hopx --version
```

<Note>
  On macOS and modern Linux systems with PEP 668, you may need to use `--user` flag or a virtual environment. The quick install script handles this automatically.
</Note>

## Verify Installation

After installation, verify the CLI is working:

```bash theme={null}
# Check version
hopx --version

# Expected output:
# hopx-cli 0.1.2

# Check help
hopx --help

# Check system health
hopx system health
```

## Update CLI

Update to the latest version:

```bash theme={null}
hopx self-update
```

Or reinstall using your original installation method:

```bash theme={null}
# With uv
uv tool install hopx-cli --force

# With pipx
pipx upgrade hopx-cli

# With pip
pip install --user --upgrade hopx-cli
```

## Post-Installation Setup

After installation, complete first-time setup:

```bash theme={null}
# Interactive setup wizard
hopx init
```

The setup wizard will:

1. Guide you through authentication
2. Help you create an API key
3. Configure default settings
4. Test your connection

Or set up manually:

```bash theme={null}
# Authenticate
hopx auth login

# Create API key
hopx auth keys create --name "my-key"

# Verify authentication
hopx auth status
```

## Troubleshooting

### Command Not Found

If `hopx` command is not found:

**Linux/macOS:**

```bash theme={null}
# Check if installed
pip show hopx-cli

# Add to PATH
export PATH="$PATH:$(python3 -m site --user-base)/bin"

# Add to shell profile (permanent)
echo 'export PATH="$PATH:$(python3 -m site --user-base)/bin"' >> ~/.bashrc
source ~/.bashrc
```

**Windows:**

```powershell theme={null}
# Check if installed
pip show hopx-cli

# Add to PATH (replace USERNAME)
$env:Path += ";C:\Users\USERNAME\AppData\Roaming\Python\Python312\Scripts"
```

### Python Version Issues

The CLI requires Python 3.12+:

```bash theme={null}
# Check Python version
python3 --version

# Should show: Python 3.12.x or higher

# If using older Python, upgrade or use pyenv
pyenv install 3.12.0
pyenv global 3.12.0
```

### Permission Errors

If you encounter permission errors:

```bash theme={null}
# Use --user flag
pip install --user hopx-cli

# Or use virtual environment
python3 -m venv venv
source venv/bin/activate
pip install hopx-cli
```

### PEP 668 Errors (macOS/Linux)

On systems with PEP 668 (external package managers), use `--user` or `pipx`:

```bash theme={null}
# Use pipx (recommended)
pipx install hopx-cli

# Or use --user
pip install --user hopx-cli
```

### Installation Verification

Test the installation:

```bash theme={null}
# Check version
hopx --version

# Check help
hopx --help

# Test system health (requires authentication)
hopx system health
```

## Platform-Specific Notes

### Linux

Works on all major Linux distributions. The quick install script detects your distribution and uses the appropriate method.

### macOS

Works on macOS 10.15+. The quick install script handles Homebrew and system Python correctly.

### Windows

Works on Windows 10+ and Windows Subsystem for Linux (WSL). For native Windows, use WSL or ensure Python 3.12+ is installed.

## Related

* **[CLI Overview](/cli/introduction)** - Learn about the CLI
* **[CLI Quickstart](/cli/quickstart)** - Get started with your first command
* **[API Key Setup](/api-key)** - Get your API key for authentication

## Next Steps

* Complete [CLI Quickstart](/cli/quickstart) to run your first command
* Learn about [Authentication](/cli/commands/auth) for CLI access
* Explore [Command Reference](/cli/commands/sandbox) for all available commands