FS

Type: filesystem API (async)

Read and write files from the script sandbox. Disabled by default. Enable Allow script file read and/or Allow script file write in Settings → General before calling these APIs. hc.parse / hc.stringify (in-memory codecs) do not require the file settings.

Use await — every hc.fs method returns a Promise.

Paths are confined to an effective root directory:

• For git-backed collections, the root is that collection's git repository directory.
• Otherwise the root is Script file access root in Settings → General, or your home directory when that field is empty.

Relative paths resolve under the root. Absolute paths must still resolve under the root. Parent segments (..) and symlink escapes outside the root are rejected. Individual reads and writes are limited to 50 MB.

hc.fs.append(path, contents)

Available since v2.0.0

Signature:(path: string, contents: string) => Promise<void>

Appends UTF-8 text to a file, creating it when missing. Requires Allow script file write.

hc.fs.exists(path)

Available since v2.0.0

Signature:(path: string) => Promise<boolean>

Returns whether the path exists under the root. Requires Allow script file read.

hc.fs.readBytes(path)

Available since v2.0.0

Signature:(path: string) => Promise<Uint8Array>

Reads a binary file as a Uint8Array. Requires Allow script file read.

hc.fs.readCsv(path, options?)

Available since v2.0.0

Signature:(path: string, options?: object) => Promise<object[] | string[][]>

Reads and parses a CSV file. Requires Allow script file read.

Option	Description
headers	When true (default), the first row becomes object keys (object[]). When false, returns string[][].
delimiter

var users = await hc.fs.readCsv("data/users.csv");
hc.request.url = "https://api.example.com/users/" + users[0].id;

hc.fs.readJson(path)

Available since v2.0.0

Signature:(path: string) => Promise<any>

Reads and parses a JSON file. Requires Allow script file read.

var config = await hc.fs.readJson("config/env.json");
hc.request.headers.set("X-Tenant", config.tenantId);

hc.fs.readText(path)

Available since v2.0.0

Signature:(path: string) => Promise<string>

Reads a UTF-8 text file. Requires Allow script file read.

var fixture = await hc.fs.readText("fixtures/payload.json");

hc.fs.readYaml(path)

Available since v2.0.0

Signature:(path: string) => Promise<any>

Reads and parses a YAML file. Requires Allow script file read.

hc.fs.stat(path)

Available since v2.0.0

Signature:(path: string) => Promise<{ size: number, mtimeMs: number, isFile: boolean, isDirectory: boolean } | null>

Returns file metadata, or null when the path does not exist. Requires Allow script file read.

hc.fs.writeBytes(path, bytes)

Available since v2.0.0

Signature:(path: string, bytes: Uint8Array) => Promise<void>

Writes binary data. Requires Allow script file write.

hc.fs.writeCsv(path, rows, options?)

Available since v2.0.0

Signature:(path: string, rows: object[] | string[][], options?: object) => Promise<void>

Serializes CSV and writes it. Requires Allow script file write. Pass headers as a string array to fix column order; otherwise object keys are inferred.

await hc.fs.writeCsv("out/results.csv", [{ id: 1, ok: true }], {
  headers: ["id", "ok"],
});

hc.fs.writeJson(path, value, options?)

Available since v2.0.0

Signature:(path: string, value: any, options?: object) => Promise<void>

Serializes JSON and writes it. Requires Allow script file write.

Option	Description
pretty	Pretty-print with indentation (default true).
indent	Indent width when pretty is true (default 2).

hc.fs.writeText(path, contents)

Available since v2.0.0

Signature:(path: string, contents: string) => Promise<void>

Writes UTF-8 text, creating parent directories as needed. Requires Allow script file write.

await hc.fs.writeText("out/last-response.txt", hc.response.text());

hc.fs.writeYaml(path, value)

Available since v2.0.0

Signature:(path: string, value: any) => Promise<void>

Serializes YAML and writes it. Requires Allow script file write.