client.files

client.files reads, writes, and lists host files through the daemon.

const source = await client.files.read('/absolute/path/to/input.txt');
const written = await client.files.write('/absolute/path/to/output.txt', source.content);
const directory = await client.files.list('/absolute/path/to');

Every path is absolute. Relative paths and ~ are not expanded. File paths are sent to the daemon unchanged; the daemon checks that they are absolute and returns a mapped API error when they are not.

Every method accepts ordinary request options in its final object: headers, signal, timeout, and maxRetries. read and write add encoding; list adds limit.

Read

await client.files.read(path, { encoding: 'utf8', timeout: 5_000 });
await client.files.read(path, { encoding: 'base64' });

read(path, options?) returns Promise<FilePeekDTO>, { path, content, truncated }, through GET /v1/files/peek. It captures at most 512 KiB of file bytes. truncated: true means content is only the prefix. Request base64 for binary content.

Write

const result = await client.files.write(path, content, { encoding: 'utf8' });
// result is { path, bytes_written }
await client.files.write(path, bytes.toString('base64'), { encoding: 'base64' });

write(path, content, options?) returns Promise<FileWriteDTO>, { path, bytes_written }. Writes create parent directories and atomically replace the target. If path is an existing symlink, the daemon resolves it and atomically replaces its destination; the symlink remains. Decoded content above 1 MiB is refused with UnprocessableEntityError carrying status: 413 and code: 'file_too_large'; it is never truncated or partially written.

List

const result = await client.files.list(path, { limit: 100 });

list(path, options?) returns Promise<FileListDTO>, { path, entries, truncated }, for one directory level. Each entry has name, type: 'file' | 'dir' | 'other', size, and ISO-8601 modified. limit must be a positive integer; the default is 1000. truncated: true means the directory had more entries than the requested limit.

Authority

The token is the owner credential. Anyone holding it can already create an agent with a bash tool, so these methods run with the daemon user's authority and do not provide a restricted file area.