Files Service

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")

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

# 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"
)

# 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

# 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")

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

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

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

# 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"
)

# 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")

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

# 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}%")

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

# 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