Files Service

TL;DR

The Files service provides client.files.read(), write(), download(), upload(), and sync() for remote file operations. Supports partial reads, atomic writes, progress callbacks, resumable downloads, recursive directory operations, file permissions, checksums, and rsync-like directory synchronization. Find files by pattern, modification time, or size.

Read, write, and transfer files on remote machines.

How do I read a remote file?


from cmdop import AsyncCMDOPClient
 
async with AsyncCMDOPClient.remote(api_key="cmd_xxx") as client:
    # Read an entire text file from the remote machine
    content = await client.files.read("my-server", "/etc/hostname")
    print(content)
 
    # Read a file as raw bytes (useful for images, binaries)
    data = await client.files.read_bytes("my-server", "/path/to/image.png")

What read options are available?


# Specify the text encoding explicitly
content = await client.files.read(
    "my-server",
    "/app/config.json",
    encoding="utf-8"
)
 
# Read a slice of a large file — start at byte 1000, read 5000 bytes
content = await client.files.read(
    "my-server",
    "/var/log/large.log",
    offset=1000,  # Start at byte 1000
    limit=5000    # Read 5000 bytes
)
 
# Read only the last N lines of a file (tail-like behavior)
lines = await client.files.read_lines(
    "my-server",
    "/var/log/app.log",
    tail=100  # Last 100 lines
)

How do I write a remote file?


# Write a UTF-8 text string to a remote file
await client.files.write(
    "my-server",
    "/app/config.yaml",
    "key: value\n"
)
 
# Write raw binary data to a remote file
await client.files.write_bytes(
    "my-server",
    "/app/data.bin",
    binary_data
)
 
# Write with restrictive permissions (owner read/write only)
await client.files.write(
    "my-server",
    "/app/secret.key",
    content,
    mode=0o600
)
 
# Atomic write — writes to a temp file first, then renames to avoid partial writes
await client.files.write(
    "my-server",
    "/app/config.yaml",
    content,
    atomic=True
)
 
# Append text to an existing file instead of overwriting
await client.files.append(
    "my-server",
    "/var/log/app.log",
    "New entry\n"
)

How do I get file information?


# Retrieve metadata for a single remote file
info = await client.files.info("my-server", "/app/data.json")
 
print(f"Size: {info.size}")            # File size in bytes
print(f"Mode: {oct(info.mode)}")       # UNIX permission bits
print(f"Owner: {info.owner}")          # File owner
print(f"Modified: {info.modified_at}") # Last modification timestamp
print(f"Is directory: {info.is_dir}")  # True if path is a directory

How do I list a remote directory?


# List all entries in a remote directory
entries = await client.files.list("my-server", "/var/log")
 
for entry in entries:
    print(f"{entry.name} - {entry.size} bytes")

What list options are available?


# List with filters: hidden files, recursive traversal, glob pattern, sorting
entries = await client.files.list(
    "my-server",
    "/home/deploy",
    include_hidden=True,   # Include dotfiles
    recursive=True,        # Descend into subdirectories
    pattern="*.py",        # Only match Python files
    sort_by="modified",    # Sort by modification time
    sort_desc=True         # Newest first
)

How do I download files?


# Download a remote file to a local path
await client.files.download(
    "my-server",
    "/var/log/app.log",
    "./app.log"
)
 
# Download with a progress callback reporting bytes downloaded vs total
def on_progress(downloaded, total):
    print(f"{downloaded}/{total} bytes")
 
await client.files.download(
    "my-server",
    "/data/large.iso",
    "./large.iso",
    on_progress=on_progress
)
 
# Resume a previously interrupted download instead of starting over
await client.files.download(
    "my-server",
    "/data/large.iso",
    "./large.iso",
    resume=True
)

How do I upload files?


# Upload a local file to a remote path
await client.files.upload(
    "./config.yaml",
    "my-server",
    "/app/config.yaml"
)
 
# Upload with a progress callback
await client.files.upload(
    "./data.tar.gz",
    "my-server",
    "/tmp/data.tar.gz",
    on_progress=on_progress
)
 
# Upload and set the file as executable (rwxr-xr-x)
await client.files.upload(
    "./script.sh",
    "my-server",
    "/app/script.sh",
    mode=0o755
)

What directory operations are available?


# Create a single directory
await client.files.mkdir("my-server", "/app/logs")
 
# Create nested directories (equivalent to mkdir -p)
await client.files.mkdir(
    "my-server",
    "/app/data/cache/images",
    parents=True
)
 
# Delete a single file
await client.files.delete("my-server", "/tmp/old.txt")
 
# Delete a directory and all its contents recursively
await client.files.delete(
    "my-server",
    "/tmp/old_dir",
    recursive=True
)
 
# Copy a file to a new path on the same machine
await client.files.copy(
    "my-server",
    "/app/config.yaml",
    "/app/config.yaml.backup"
)
 
# Move or rename a file on the remote machine
await client.files.move(
    "my-server",
    "/app/old.txt",
    "/app/new.txt"
)

How do I manage file permissions?


# Check whether a remote path exists
exists = await client.files.exists("my-server", "/app/config.yaml")
 
# Change file permission bits (chmod)
await client.files.chmod("my-server", "/app/script.sh", 0o755)
 
# Change file owner and group (chown)
await client.files.chown("my-server", "/app/data", "deploy", "deploy")

How do I find files?


# Find files matching a glob pattern under a directory
files = await client.files.find(
    "my-server",
    "/app",
    pattern="*.log"
)
 
# Find files modified within the last 24 hours
from datetime import datetime, timedelta
 
files = await client.files.find(
    "my-server",
    "/var/log",
    modified_after=datetime.now() - timedelta(hours=24)
)
 
# Find files larger than 100 MB
files = await client.files.find(
    "my-server",
    "/",
    min_size=100 * 1024 * 1024  # > 100MB
)

How do I check disk usage?


# Get the total size of a directory in bytes
size = await client.files.du("my-server", "/var/log")
print(f"{size / 1024 / 1024:.2f} MB")
 
# Get disk free space and usage percentage for a mount point
disk = await client.files.df("my-server", "/")
print(f"Free: {disk.free / 1024**3:.1f} GB")
print(f"Used: {disk.percent}%")

How do I verify file integrity?


# Compute the MD5 checksum of a remote file
checksum = await client.files.checksum("my-server", "/data/backup.tar.gz")
print(f"MD5: {checksum}")
 
# Download and automatically verify the checksum matches
await client.files.download(
    "my-server",
    "/data/backup.tar.gz",
    "./backup.tar.gz",
    verify_checksum=True
)

Error Handling


# Import specific exception types for granular error handling
from cmdop.exceptions import (
    FileNotFoundError,
    PermissionError,
    DiskFullError
)
 
try:
    content = await client.files.read("my-server", "/etc/shadow")
except FileNotFoundError:
    print("File not found")    # Path does not exist on the remote machine
except PermissionError:
    print("Access denied")     # Insufficient privileges to read the file

Browser Service — Browser automation
AI Agent Service — AI operations