Skip to main content

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.

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