Skip to main content
The HopX CLI provides terminal access to HopX cloud sandboxes - secure, isolated VMs that start in seconds. Execute code, manage files, run commands, and build custom templates from your terminal.

​
What is the HopX CLI?

The HopX CLI is the official command-line interface for HopX.ai cloud sandboxes. It provides terminal-based access to all HopX features including sandbox management, code execution, file operations, and template building. Version: 0.1.2
Python Support: 3.12+
Framework: Typer (built on Click)

​
Use Cases

  • AI agent code execution - Execute AI-generated code safely in isolated environments
  • Running untrusted code - Test code without risking your local machine
  • Integration testing - Run tests in clean, reproducible environments
  • Data processing pipelines - Process data in isolated sandboxes
  • Browser automation - Automate browser interactions with desktop features
  • Educational environments - Create learning environments for students

​
When to Use CLI vs SDK vs API

​
Use CLI When:

  • You prefer command-line workflows
  • You’re writing shell scripts or automation
  • You need quick one-off operations
  • You’re integrating with CI/CD pipelines
  • You want interactive terminal sessions

​
Use SDK When:

  • You’re building applications in Python or JavaScript
  • You need programmatic control in your code
  • You want type safety and IDE support
  • You’re building libraries or frameworks

​
Use API When:

  • You’re building in languages without SDK support
  • You need direct HTTP control
  • You’re building custom integrations
  • You need fine-grained request/response handling

​
Command Groups

The CLI provides 15 command groups for complete sandbox management:
CommandAliasDescription
init-First-run setup wizard
auth-Authentication management
sandboxsbSandbox lifecycle management
run-Code execution
filesfFile operations
cmd-Shell commands
env-Environment variables
terminaltermInteractive terminal sessions
templatetplTemplate management
config-Configuration management
system-Health checks and metrics
org-Organization settings
profile-User profile management
members-Organization member management
billing-Billing information
usage-Usage statistics

​
Quick Example

# Install CLI
curl -fsSL https://raw.githubusercontent.com/hopx-ai/hopx/main/cli/scripts/install.sh | bash

# Authenticate
hopx auth login

# Create sandbox
hopx sandbox create --template python

# Execute code
hopx run "print('Hello, World!')"

​
Features

​
Authentication

  • Browser-based OAuth login (Google, GitHub)
  • API key management (create, list, revoke)
  • Secure credential storage via system keyring
  • Multi-profile support for different environments

​
Output Formats

  • Table (default) - Human-readable tables with borders
  • JSON - Machine-readable JSON for scripting
  • Plain - Minimal text output for piping

​
Configuration

  • YAML configuration file (~/.hopx/config.yaml)
  • Environment variable support (HOPX_* prefix)
  • Multiple profiles for dev/prod environments
  • Config precedence: CLI flags > environment > config file > defaults

​
Exit Codes

The CLI uses standardized exit codes for scripting automation:
CodeMeaning
0Success
1General error
2Validation error
3Authentication error
4Not found
5Timeout
6Network error
7Rate limit
130Interrupted (Ctrl+C)

​
Global Options

All commands support these global options: 
--api-key TEXT      API key (overrides HOPX_API_KEY)
--profile TEXT      Configuration profile (default: "default")
--output, -o FORMAT Output format: table, json, plain
-q, --quiet         Suppress non-essential output
-v, --verbose       Increase output verbosity
--no-color          Disable colored output
--version           Show version and exit
--help              Show help message

​
Next Steps