Files

All methods return typed result objects.

FilesAPI.read

async files.read(file_path, *, offset=None, limit=None, pages=None) -> ReadResult

Read a file from the sandbox filesystem. Supports text, image, and multi-page content.

Parameter	Type	Default	Description
`file_path`	`str`		Path to the file.
`offset`	`int \| None`	`None`	Starting line for text files.
`limit`	`int \| None`	`None`	Max lines to read.
`pages`	`str \| None`	`None`	Page range for PDFs (e.g. `'1-5'`).

read = await client.files.read("/tmp/demo.txt")
print(read.file.content)
print(read.file.num_lines)

async files.write(file_path, content) -> WriteResult

Write content to a file. Creates the file if it does not exist.

written = await client.files.write("/tmp/demo.txt", "hello\n")
print(written.file_path)

async files.edit(file_path, *, old_string, new_string, replace_all=False) -> EditResult

Edit a file by replacing text. Returns a structured patch.

Parameter	Type	Default	Description
`file_path`	`str`		Path to the file.
`old_string`	`str`		Text to replace.
`new_string`	`str`		Replacement text.
`replace_all`	`bool`	`False`	Replace all occurrences.

async files.glob(pattern, *, path=None) -> GlobResult

glob = await client.files.glob("**/*.rs", path=runtime.base_workdir)
print(glob.search_path, glob.num_files)

async files.grep(pattern, *, path=None, glob=None, output_mode=None, ...) -> GrepResult

Search file contents with regex. Supports the full Grep tool parameter set.

Parameter	Type	Default	Description
`pattern`	`str`		Regex pattern to search for.
`path`	`str \| None`	`None`	Root directory to search.
`glob`	`str \| None`	`None`	File filter glob (e.g. `'*.py'`).
`output_mode`	`str \| None`	`None`	`'content'`, `'files_with_matches'`, or `'count'`.

grep = await client.files.grep("TODO", path=runtime.base_workdir)
print(grep.num_matches)

Upload and download raw bytes through the SDK-only HTTP endpoint (/sdk/file). Meant for SDK and GUI integrations.

blob = await client.files.upload_bytes(
    "artifacts/report.pdf",
    pdf_bytes,
)
print(blob.file_path, blob.bytes_written, blob.created)

data = await client.files.download_bytes("artifacts/report.pdf")
print(len(data))

Upload a local file to the sandbox.

Download a remote file to the local filesystem.