Read & Write Files

from cmdop import AsyncCMDOPClient
 
async with AsyncCMDOPClient.remote(api_key="cmd_xxx") as client:
    # Read the entire file as a string
    content = await client.files.read("my-server", "/etc/hostname")
    print(content)
 
    # Read a file with explicit encoding
    text = await client.files.read(
        "my-server",
        "/app/config.json",
        encoding="utf-8"
    )

# Read raw bytes from a remote file (images, executables, etc.)
data = await client.files.read_bytes("my-server", "/path/to/image.png")
 
# Save the downloaded bytes to a local file
with open("image.png", "wb") as f:
    f.write(data)

# Read just the first 1000 bytes of a large file
content = await client.files.read(
    "my-server",
    "/var/log/large.log",
    limit=1000
)
 
# Read 1000 bytes starting from byte offset 5000
content = await client.files.read(
    "my-server",
    "/var/log/large.log",
    offset=5000,
    limit=1000
)

# Read the entire file and return each line as a list element
lines = await client.files.read_lines("my-server", "/etc/hosts")
 
for line in lines:
    print(line)
 
# Read only the last 100 lines (equivalent to tail -n 100)
last_lines = await client.files.read_lines(
    "my-server",
    "/var/log/app.log",
    tail=100
)

# Write a plain text string to a remote file (creates or overwrites)
await client.files.write(
    "my-server",
    "/app/config.yaml",
    "key: value\nother: data\n"
)
 
# Write a file and set restrictive permissions (owner-read only)
await client.files.write(
    "my-server",
    "/app/secret.key",
    "secret-content",
    mode=0o600  # Only owner can read
)

# Read a local binary file into memory
with open("local_image.png", "rb") as f:
    data = f.read()
 
# Write the binary data to a remote path
await client.files.write_bytes(
    "my-server",
    "/app/image.png",
    data
)

# Add text to the end of a file without overwriting existing content
await client.files.append(
    "my-server",
    "/var/log/app.log",
    "New log entry\n"
)

# Write to a temp file first, then rename — prevents partial writes on failure
await client.files.write(
    "my-server",
    "/app/config.yaml",
    new_config,
    atomic=True  # Prevents partial writes
)

# Retrieve detailed metadata for a single file
info = await client.files.info("my-server", "/app/data.json")
 
print(f"Size: {info.size} bytes")
print(f"Modified: {info.modified_at}")
print(f"Mode: {oct(info.mode)}")
print(f"Owner: {info.owner}")
print(f"Is directory: {info.is_dir}")

# Returns True/False without reading the file content
exists = await client.files.exists("my-server", "/app/config.yaml")
 
# Only create the config file if it does not already exist
if not exists:
    await client.files.write("my-server", "/app/config.yaml", default_config)

# Duplicate a file to a new path on the same remote server
await client.files.copy(
    "my-server",
    "/app/config.yaml",
    "/app/config.yaml.backup"
)

# Move or rename a file (atomic operation on most filesystems)
await client.files.move(
    "my-server",
    "/app/old_name.txt",
    "/app/new_name.txt"
)

# Delete a single file
await client.files.delete("my-server", "/tmp/temp_file.txt")
 
# Delete a directory and all its contents recursively
await client.files.delete(
    "my-server",
    "/tmp/temp_dir",
    recursive=True
)

# Set file permissions (e.g., make a script executable)
await client.files.chmod("my-server", "/app/script.sh", 0o755)
 
# Change file owner and group (requires root privileges)
await client.files.chown("my-server", "/app/data", "deploy", "deploy")

# Create a single directory
await client.files.mkdir("my-server", "/app/logs")
 
# Create nested directories in one call (equivalent to mkdir -p)
await client.files.mkdir(
    "my-server",
    "/app/data/cache/images",
    parents=True
)

from cmdop.exceptions import (
    FileNotFoundError,
    PermissionError,
    IsADirectoryError
)
 
try:
    content = await client.files.read("my-server", "/etc/shadow")
except PermissionError:
    # Raised when the user lacks read access to the file
    print("Access denied")
except FileNotFoundError:
    # Raised when the specified path does not exist
    print("File not found")

import json
 
# Read a JSON config file and parse it into a Python dict
content = await client.files.read("my-server", "/app/config.json")
config = json.loads(content)
 
# Modify a value in the parsed config
config["debug"] = True
 
# Serialize back to JSON and write to the remote server
await client.files.write(
    "my-server",
    "/app/config.json",
    json.dumps(config, indent=2)
)

import yaml
 
# Read a YAML config file and parse it into a Python dict
content = await client.files.read("my-server", "/app/config.yaml")
config = yaml.safe_load(content)
 
# Update a nested config value
config["logging"]["level"] = "debug"
 
# Serialize back to YAML and write to the remote server
await client.files.write(
    "my-server",
    "/app/config.yaml",
    yaml.dump(config)
)

import configparser
import io
 
# Read an INI config file and parse it with ConfigParser
content = await client.files.read("my-server", "/app/settings.ini")
config = configparser.ConfigParser()
config.read_string(content)
 
# Update a value in the [database] section
config["database"]["host"] = "new-host"
 
# Serialize back to INI format and write to the remote server
output = io.StringIO()
config.write(output)
await client.files.write(
    "my-server",
    "/app/settings.ini",
    output.getvalue()
)

# Atomic write prevents corruption if the connection drops mid-write
await client.files.write(
    "my-server",
    "/app/config.yaml",
    new_config,
    atomic=True
)

# Always back up a file before modifying it in place
await client.files.copy(
    "my-server",
    "/app/config.yaml",
    f"/app/config.yaml.{datetime.now().isoformat()}"
)

# For files too large to hold in memory, use download instead of read
await client.files.download(
    "my-server",
    "/data/large.db",
    "./large.db"
)