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

# File Operations

> Complete reference for HopX CLI file commands - read, write, list, upload, download, delete, and manage files in sandboxes. Includes all flags, options, examples, and exit codes.

Manage files in HopX sandboxes using the `files` command (alias: `f`). Read, write, list, upload, download, and delete files from the command line.

## Command Syntax

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

## Subcommands

### `read`

Read file contents from a sandbox.

**Syntax:**

```bash theme={null}
hopx files read SANDBOX_ID PATH [OPTIONS]
```

**Arguments:**

* `SANDBOX_ID` - Sandbox ID (required)
* `PATH` - File path to read (required)

**Options:**

* `--output, -o FORMAT` - Output format: `table`, `json`, `plain` (default: `table`)

**Examples:**

```bash theme={null}
# Read file
hopx files read sb_abc123 /app/config.json

# Read with JSON output
hopx files read sb_abc123 /app/data.txt --output json
```

**Expected Output:**

```
{"key": "value"}
```

**Exit Codes:**

* `0` - Success
* `3` - Authentication error
* `4` - Sandbox or file not found

### `write`

Write data to a file in a sandbox.

**Syntax:**

```bash theme={null}
hopx files write SANDBOX_ID PATH [OPTIONS]
```

**Arguments:**

* `SANDBOX_ID` - Sandbox ID (required)
* `PATH` - File path to write (required)

**Options:**

* `--data, -d TEXT` - Data to write (use `-` to read from stdin)

**Examples:**

```bash theme={null}
# Write file with data
hopx files write sb_abc123 /app/config.json --data '{"key": "value"}'

# Write from stdin
echo "Hello, World!" | hopx files write sb_abc123 /app/data.txt --data -

# Write from file
cat local.txt | hopx files write sb_abc123 /app/data.txt --data -
```

**Expected Output:**

```
✓ File written: /app/config.json
```

**Exit Codes:**

* `0` - Success
* `3` - Authentication error
* `4` - Sandbox not found

### `list`

List files and directories in a sandbox.

**Syntax:**

```bash theme={null}
hopx files list SANDBOX_ID [PATH] [OPTIONS]
```

**Arguments:**

* `SANDBOX_ID` - Sandbox ID (required)
* `PATH` - Directory path (optional, default: `/workspace`)

**Options:**

* `--output, -o FORMAT` - Output format: `table`, `json`, `plain` (default: `table`)

**Examples:**

```bash theme={null}
# List files in workspace
hopx files list sb_abc123

# List files in specific directory
hopx files list sb_abc123 /app/

# List with JSON output
hopx files list sb_abc123 --output json
```

**Expected Output (Table):**

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

**Exit Codes:**

* `0` - Success
* `3` - Authentication error
* `4` - Sandbox not found

### `delete`

Delete a file or directory from a sandbox.

**Syntax:**

```bash theme={null}
hopx files delete SANDBOX_ID PATH [OPTIONS]
```

**Arguments:**

* `SANDBOX_ID` - Sandbox ID (required)
* `PATH` - File or directory path to delete (required)

**Options:**

* `--force` - Skip confirmation prompt

**Examples:**

```bash theme={null}
# Delete file
hopx files delete sb_abc123 /app/temp.txt

# Delete without confirmation
hopx files delete sb_abc123 /app/temp.txt --force
```

**Expected Output:**

```
✓ File deleted: /app/temp.txt
```

**Exit Codes:**

* `0` - Success
* `3` - Authentication error
* `4` - Sandbox or file not found

### `upload`

Upload a local file to a sandbox.

**Syntax:**

```bash theme={null}
hopx files upload SANDBOX_ID LOCAL_PATH REMOTE_PATH [OPTIONS]
```

**Arguments:**

* `SANDBOX_ID` - Sandbox ID (required)
* `LOCAL_PATH` - Local file path (required)
* `REMOTE_PATH` - Remote file path in sandbox (required)

**Examples:**

```bash theme={null}
# Upload local file
hopx files upload sb_abc123 ./local.txt /app/remote.txt

# Upload with progress
hopx files upload sb_abc123 ./large.csv /app/data.csv
```

**Expected Output:**

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

**Exit Codes:**

* `0` - Success
* `3` - Authentication error
* `4` - Sandbox not found

### `download`

Download a file from a sandbox to local filesystem.

**Syntax:**

```bash theme={null}
hopx files download SANDBOX_ID REMOTE_PATH LOCAL_PATH [OPTIONS]
```

**Arguments:**

* `SANDBOX_ID` - Sandbox ID (required)
* `REMOTE_PATH` - Remote file path in sandbox (required)
* `LOCAL_PATH` - Local file path (required)

**Examples:**

```bash theme={null}
# Download file
hopx files download sb_abc123 /app/data.txt ./local.txt

# Download with progress
hopx files download sb_abc123 /app/result.csv ./result.csv
```

**Expected Output:**

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

**Exit Codes:**

* `0` - Success
* `3` - Authentication error
* `4` - Sandbox or file not found

### `info`

Get detailed information about a file or directory.

**Syntax:**

```bash theme={null}
hopx files info SANDBOX_ID PATH [OPTIONS]
```

**Arguments:**

* `SANDBOX_ID` - Sandbox ID (required)
* `PATH` - File or directory path (required)

**Options:**

* `--output, -o FORMAT` - Output format: `table`, `json`, `plain` (default: `table`)

**Examples:**

```bash theme={null}
# Get file info
hopx files info sb_abc123 /app/config.json

# Get info with JSON output
hopx files info sb_abc123 /app/data.txt --output json
```

**Expected Output (Table):**

```
┌─────────────┬─────────────────────────────────────┐
│ Property    │ Value                               │
├─────────────┼─────────────────────────────────────┤
│ Name        │ config.json                         │
│ Path        │ /app/config.json                    │
│ Size        │ 234 B                               │
│ Type        │ file                                │
│ Modified    │ 2025-01-27 10:00:00                 │
└─────────────┴─────────────────────────────────────┘
```

**Exit Codes:**

* `0` - Success
* `3` - Authentication error
* `4` - Sandbox or file not found

## Shell Scripting Examples

### Upload and Process File

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

SANDBOX_ID="sb_abc123"

# Upload file
hopx files upload "$SANDBOX_ID" ./data.csv /app/data.csv

# Process file
hopx run "import pandas as pd; df = pd.read_csv('/app/data.csv'); print(df.head())" --sandbox "$SANDBOX_ID"
```

### Download Results

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

# Download file
hopx files download sb_abc123 /app/results.json ./results.json

# Process locally
jq '.summary' ./results.json
```

### Batch File Operations

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

# List files and download each
hopx files list sb_abc123 /app/ --output json | jq -r '.[].name' | while read file; do
    echo "Downloading $file..."
    hopx files download sb_abc123 "/app/$file" "./$file"
done
```

## 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
* **[Python SDK: Files](/sdk/python/files)** - Python SDK file operations
* **[JavaScript SDK: Files](/sdk/javascript/files)** - JavaScript SDK file operations
* **[API: File Operations](/api/vm-agent/read-file)** - REST API endpoints

## Next Steps

* Learn about [Code Execution](/cli/commands/run) to process files
* Explore [Environment Variables](/cli/commands/env) to configure file operations
* Review [Sandbox Management](/cli/commands/sandbox) to create and manage sandboxes