Skip to main content
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
The quick install script handles everything automatically, including PEP 668 environments on macOS/modern Linux: 
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 is a fast Python package installer: 
# 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 installs Python applications in isolated environments: 
# 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: 
# 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
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.

​
Verify Installation

After installation, verify the CLI is working: 
# 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: 
hopx self-update
Or reinstall using your original installation method: 
# 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: 
# 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: 
# 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: 
# 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: 
# 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+: 
# 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: 
# 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: 
# Use pipx (recommended)
pipx install hopx-cli

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

​
Installation Verification

Test the installation: 
# 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.

​
Next Steps