Skip to main content
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

hopx files <subcommand> [options]

​
Subcommands

​
read

Read file contents from a sandbox. Syntax: 
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: 
# 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: 
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: 
# 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: 
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: 
# 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: 
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: 
# 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: 
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: 
# 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: 
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: 
# 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: 
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: 
# 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

#!/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

#!/bin/bash

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

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

​
Batch File Operations

#!/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

​
Next Steps