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

# Quickstart

> Get started with the HopX CLI in 5 minutes. Learn how to install, authenticate, create your first sandbox, execute code, and manage files from the command line.

Get up and running with the HopX CLI in 5 minutes. This guide walks you through installation, authentication, creating your first sandbox, executing code, and managing files.

## What You'll Learn

In this quickstart, you'll learn how to:

* Install the HopX CLI
* Authenticate with your API key
* Create your first sandbox
* Execute code in multiple languages
* Manage files in sandboxes
* Clean up sandboxes

## Prerequisites

* [HopX API key](https://console.hopx.dev) (get one [here](/api-key) if you don't have it)
* Python 3.12+ installed
* Terminal access

## Step 1: Install the CLI

Install the CLI using the quick install script:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/hopx-ai/hopx/main/cli/scripts/install.sh | bash
```

**Expected Output:**

```
✓ HopX CLI installed successfully
✓ Version: 0.1.2
✓ Run 'hopx init' to get started
```

Verify installation:

```bash theme={null}
hopx --version
```

**Expected Output:**

```
hopx-cli 0.1.2
```

## Step 2: Authenticate

### Option 1: Interactive Setup (Recommended)

Run the interactive setup wizard:

```bash theme={null}
hopx init
```

The wizard will:

1. Guide you through browser-based OAuth login
2. Help you create an API key
3. Configure default settings
4. Test your connection

### Option 2: Manual Authentication

Authenticate manually:

```bash theme={null}
# Browser login
hopx auth login

# Create API key
hopx auth keys create --name "my-key"

# Verify authentication
hopx auth status
```

**Expected Output:**

```
✓ Authenticated
✓ API key: hopx_live_... (configured)
```

### Option 3: Environment Variable

Set your API key as an environment variable:

```bash theme={null}
export HOPX_API_KEY="hopx_live_..."
```

Get your API key at [console.hopx.dev](https://console.hopx.dev).

## Step 3: Create Your First Sandbox

Create a sandbox from a pre-built template:

```bash theme={null}
hopx sandbox create --template python
```

**Expected Output:**

```
✓ Sandbox created: sb_abc123
✓ Status: running
✓ Template: python
```

List your sandboxes:

```bash theme={null}
hopx sandbox list
```

**Expected Output:**

```
┌──────────────────┬─────────┬────────────┐
│ ID               │ Status  │ Template   │
├──────────────────┼─────────┼────────────┤
│ sb_abc123        │ running │ python     │
└──────────────────┴─────────┴────────────┘
```

## Step 4: Execute Code

Execute Python code in your sandbox:

```bash theme={null}
hopx run "print('Hello, World!')"
```

**Expected Output:**

```
Hello, World!
```

Execute code from a file:

```bash theme={null}
# Create a local file
echo "print('Hello from file!')" > script.py

# Execute from file
hopx run -f script.py
```

**Expected Output:**

```
Hello from file!
```

Execute JavaScript:

```bash theme={null}
hopx run "console.log('Hello from JavaScript!')" -l javascript
```

**Expected Output:**

```
Hello from JavaScript!
```

Execute Bash:

```bash theme={null}
hopx run "echo 'Hello from Bash!'" -l bash
```

**Expected Output:**

```
Hello from Bash!
```

## Step 5: Manage Files

Write a file to your sandbox:

```bash theme={null}
hopx files write sb_abc123 /app/data.txt "Hello, World!"
```

**Expected Output:**

```
✓ File written: /app/data.txt
```

Read the file:

```bash theme={null}
hopx files read sb_abc123 /app/data.txt
```

**Expected Output:**

```
Hello, World!
```

List files in a directory:

```bash theme={null}
hopx files list sb_abc123 /app/
```

**Expected Output:**

```
┌──────────────┬──────┬─────────────────────┐
│ Name         │ Size │ Modified            │
├──────────────┼──────┼─────────────────────┤
│ data.txt     │ 13   │ 2025-01-27 10:00:00 │
└──────────────┴──────┴─────────────────────┘
```

Upload a local file:

```bash theme={null}
# Create local file
echo "Local content" > local.txt

# Upload to sandbox
hopx files upload sb_abc123 ./local.txt /app/uploaded.txt
```

**Expected Output:**

```
✓ File uploaded: /app/uploaded.txt
```

Download a file:

```bash theme={null}
hopx files download sb_abc123 /app/data.txt ./downloaded.txt
```

**Expected Output:**

```
✓ File downloaded: ./downloaded.txt
```

## Step 6: Run Shell Commands

Run shell commands in your sandbox:

```bash theme={null}
hopx cmd run sb_abc123 "ls -la /app"
```

**Expected Output:**

```
total 16
drwxr-xr-x 2 user user 4096 Jan 27 10:00 .
drwxr-xr-x 3 user user 4096 Jan 27 10:00 ..
-rw-r--r-- 1 user user   13 Jan 27 10:00 data.txt
-rw-r--r-- 1 user user   14 Jan 27 10:00 uploaded.txt
```

Install packages:

```bash theme={null}
hopx cmd run sb_abc123 "pip install requests"
```

**Expected Output:**

```
Collecting requests
  Downloading requests-2.31.0-py3-none-any.whl (62 kB)
...
Successfully installed requests-2.31.0
```

## Step 7: Manage Environment Variables

Set environment variables:

```bash theme={null}
hopx env set sb_abc123 API_KEY=secret123 DEBUG=true
```

**Expected Output:**

```
✓ Environment variables set
```

List environment variables:

```bash theme={null}
hopx env list sb_abc123
```

**Expected Output:**

```
┌───────────┬─────────────┐
│ Variable  │ Value       │
├───────────┼─────────────┤
│ API_KEY   │ secret123   │
│ DEBUG     │ true        │
└───────────┴─────────────┘
```

Get a specific variable:

```bash theme={null}
hopx env get sb_abc123 API_KEY
```

**Expected Output:**

```
secret123
```

## Step 8: Clean Up

Kill your sandbox when done:

```bash theme={null}
hopx sandbox kill sb_abc123
```

**Expected Output:**

```
✓ Sandbox killed: sb_abc123
```

Or pause it to preserve state:

```bash theme={null}
hopx sandbox pause sb_abc123
```

**Expected Output:**

```
✓ Sandbox paused: sb_abc123
```

Resume later:

```bash theme={null}
hopx sandbox resume sb_abc123
```

**Expected Output:**

```
✓ Sandbox resumed: sb_abc123
```

## Next Steps

Now that you've completed the quickstart, explore more CLI features:

* **[Sandbox Management](/cli/commands/sandbox)** - Complete sandbox lifecycle management
* **[Code Execution](/cli/commands/run)** - Execute code in multiple languages
* **[File Operations](/cli/commands/files)** - Advanced file management
* **[Shell Commands](/cli/commands/cmd)** - Run system commands
* **[Environment Variables](/cli/commands/env)** - Manage environment configuration
* **[Templates](/cli/commands/template)** - List and build custom templates
* **[Configuration](/cli/commands/config)** - Configure CLI settings and profiles

## Related

* **[CLI Overview](/cli/introduction)** - Learn about CLI features
* **[CLI Installation](/cli/installation)** - Detailed installation guide
* **[Python SDK Quickstart](/sdk/python/quickstart)** - Get started with Python SDK
* **[JavaScript SDK Quickstart](/sdk/javascript/quickstart)** - Get started with JavaScript SDK