> ## 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.

# Overview

> Official HopX CLI for managing cloud sandboxes from the command line. Install the CLI, authenticate with your API key, and start creating sandboxes, executing code, managing files, and automating workflows. Complete command-line interface reference with examples for all 15 command groups.

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:

| Command    | Alias  | Description                    |
| ---------- | ------ | ------------------------------ |
| `init`     | -      | First-run setup wizard         |
| `auth`     | -      | Authentication management      |
| `sandbox`  | `sb`   | Sandbox lifecycle management   |
| `run`      | -      | Code execution                 |
| `files`    | `f`    | File operations                |
| `cmd`      | -      | Shell commands                 |
| `env`      | -      | Environment variables          |
| `terminal` | `term` | Interactive terminal sessions  |
| `template` | `tpl`  | Template 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

```bash theme={null}
# 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:

| Code | Meaning              |
| ---- | -------------------- |
| 0    | Success              |
| 1    | General error        |
| 2    | Validation error     |
| 3    | Authentication error |
| 4    | Not found            |
| 5    | Timeout              |
| 6    | Network error        |
| 7    | Rate limit           |
| 130  | Interrupted (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
```

## Related

* **[CLI Installation](/cli/installation)** - Install the CLI
* **[CLI Quickstart](/cli/quickstart)** - Get started in 5 minutes
* **[Python SDK Overview](/sdk/python/introduction)** - Python SDK reference
* **[JavaScript SDK Overview](/sdk/javascript/introduction)** - JavaScript SDK reference
* **[API Overview](/api/introduction)** - REST API reference

## Next Steps

* Follow the [Installation Guide](/cli/installation) to install the CLI
* Complete the [Quickstart Guide](/cli/quickstart) to run your first command
* Explore [Command Reference](/cli/commands/sandbox) for detailed command documentation