Installation

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:

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:

Guide you through authentication
Help you create an API key
Configure default settings
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.

CLI Overview - Learn about the CLI
CLI Quickstart - Get started with your first command
API Key Setup - Get your API key for authentication

Next Steps

Complete CLI Quickstart to run your first command
Learn about Authentication for CLI access
Explore Command Reference for all available commands

Getting Started

Setup

Commands

Prerequisites

Quick Install (Recommended)

Alternative Installation Methods

uv (Fastest)

pipx (Isolated)

pip (User Install)

Verify Installation

Update CLI

Post-Installation Setup

Troubleshooting

Command Not Found

Python Version Issues

Permission Errors

PEP 668 Errors (macOS/Linux)

Installation Verification

Platform-Specific Notes

Linux

macOS

Windows

Next Steps

​Prerequisites

​Quick Install (Recommended)

​Alternative Installation Methods

​uv (Fastest)

​pipx (Isolated)

​pip (User Install)

​Verify Installation

​Update CLI

​Post-Installation Setup

​Troubleshooting

​Command Not Found

​Python Version Issues

​Permission Errors

​PEP 668 Errors (macOS/Linux)

​Installation Verification

​Platform-Specific Notes

​Linux

​macOS

​Windows

​Related

​Next Steps

Prerequisites

Quick Install (Recommended)

Alternative Installation Methods

uv (Fastest)

pipx (Isolated)

pip (User Install)

Verify Installation

Update CLI

Post-Installation Setup

Troubleshooting

Command Not Found

Python Version Issues

Permission Errors

PEP 668 Errors (macOS/Linux)

Installation Verification

Platform-Specific Notes

Linux

macOS

Windows

Related

Next Steps