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

# Shell Commands

> Execute shell commands in HopX sandboxes using the CLI cmd command. Run commands synchronously or in the background with options for timeouts, working directories, and environment variables.

Execute shell commands in HopX sandboxes using the `cmd` command. Run commands synchronously or in the background with full control over execution environment.

## Command Syntax

```bash theme={null}
hopx cmd <subcommand> [options]
```

## Subcommands

### `run`

Run a shell command synchronously.

**Syntax:**

```bash theme={null}
hopx cmd run SANDBOX_ID COMMAND [OPTIONS]
```

**Arguments:**

* `SANDBOX_ID` - Sandbox ID (required)
* `COMMAND` - Shell command to execute (required)

**Options:**

* `--timeout INTEGER` - Command timeout in seconds
* `--workdir TEXT` - Working directory for command execution
* `--env TEXT` - Environment variable in KEY=VALUE format (repeatable)
* `--background` - Run command in background (returns immediately)
* `--output, -o FORMAT` - Output format: `table`, `json`, `plain` (default: `table`)

**Examples:**

```bash theme={null}
# Run simple command
hopx cmd run sb_abc123 "ls -la"

# Run with timeout
hopx cmd run sb_abc123 "npm install" --timeout 300

# Run in working directory
hopx cmd run sb_abc123 "pwd" --workdir /app

# Run with environment variables
hopx cmd run sb_abc123 "echo $API_KEY" --env API_KEY=secret123

# Run in background
hopx cmd run sb_abc123 "python server.py" --background

# Get JSON output
hopx cmd run sb_abc123 "ls -la" --output json
```

**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
```

**Expected Output (JSON):**

```json theme={null}
{
  "stdout": "total 16\ndrwxr-xr-x 2 user user 4096 Jan 27 10:00 .\n",
  "stderr": "",
  "exit_code": 0,
  "execution_time": 0.5
}
```

**Exit Codes:**

* `0` - Success
* `1` - Command execution error
* `3` - Authentication error
* `4` - Sandbox not found
* `5` - Timeout

### `exec`

Execute a shell command (alias for `run`).

**Syntax:**

```bash theme={null}
hopx cmd exec SANDBOX_ID COMMAND [OPTIONS]
```

Same as `run` command. See `run` for options and examples.

## Shell Scripting Examples

### Install Dependencies

```bash theme={null}
#!/bin/bash
set -e

SANDBOX_ID="sb_abc123"

# Install packages
hopx cmd run "$SANDBOX_ID" "pip install requests pandas" --timeout 120

# Verify installation
hopx cmd run "$SANDBOX_ID" "pip list | grep requests"
```

### Run Tests

```bash theme={null}
#!/bin/bash

# Run tests with environment variables
hopx cmd run sb_abc123 "npm test" \
  --env NODE_ENV=test \
  --env CI=true \
  --workdir /app
```

### Background Process

```bash theme={null}
#!/bin/bash

# Start server in background
hopx cmd run sb_abc123 "python server.py" --background

# Server is now running in background
# Use other commands to interact with it
```

### Chain Commands

```bash theme={null}
#!/bin/bash

# Chain multiple commands
hopx cmd run sb_abc123 "cd /app && npm install && npm test"
```

## Related

* **[CLI Quickstart](/cli/quickstart)** - Get started with CLI
* **[Sandbox Commands](/cli/commands/sandbox)** - Manage sandboxes
* **[Code Execution](/cli/commands/run)** - Execute code in sandboxes
* **[Environment Variables](/cli/commands/env)** - Manage environment variables
* **[Python SDK: Commands](/sdk/python/commands)** - Python SDK command execution
* **[JavaScript SDK: Commands](/sdk/javascript/commands)** - JavaScript SDK command execution
* **[API: Run Command](/api/vm-agent/run-command)** - REST API endpoint

## Next Steps

* Learn about [Code Execution](/cli/commands/run) to run code alongside commands
* Explore [File Operations](/cli/commands/files) to work with files via commands
* Review [Environment Variables](/cli/commands/env) to configure command execution