Files (MFS) Operations | IPFS

What MFS is: the Mutable File System is a virtual, UNIX-like filesystem layered on top of IPFS's immutable content-addressed objects — it lets a workflow build up a directory tree with normal paths (/reports/2026/q1.csv) while IPFS handles the underlying CIDs.

copy

Field	Type	Required	Default
`mfsSourcePath`	text	✓ Yes	MFS path or `/ipfs/<cid>[/path]`
`mfsDestPath`	text	✓ Yes	Absolute destination MFS path
`parents`	bool	No	`false` — create intermediate destination directories
`force`	bool	No	`false` — overwrite existing destination

Missing paths → CFG_MISSING_SOURCE_PATH / CFG_MISSING_DEST_PATH. Response: { mfsSourcePath, mfsDestPath } (Kubo returns no CID for this call).

flush

Field	Type	Required	Default
`mfsPath`	text	No	`/` — root flushes the entire tree

Response: { mfsPath, cid }.

list

Field	Type	Required	Default
`mfsPath`	text	No	`/`
`unsorted`	bool	No	`false` — skip Kubo's alphabetical sort

Response: array of { name, cid, size, type }, plus count.

makeDirectory

Field	Type	Required	Default
`mfsPath`	text	✓ Yes	—
`parents`	bool	No	`true` — this node's default diverges from Kubo's own default of `false`
`cidVersion`	int	No	`0`
`hashFunction`	text	No	`sha2-256`

Missing path → CFG_MISSING_PATH. Response: { mfsPath } — Kubo doesn't return a CID for a directory creation; call files/stat or files/flush afterward if you need it.

move

Field	Type	Required
`mfsSourcePath`	text	✓ Yes
`mfsDestPath`	text	✓ Yes

MFS-only (no /ipfs/<cid> source support, unlike copy). The destination's parent directory must already exist — no parents option. Missing paths → CFG_MISSING_SOURCE_PATH / CFG_MISSING_DEST_PATH. Response: { mfsSourcePath, mfsDestPath }.

read

Binary output.

Field	Type	Required	Default
`mfsPath`	text	✓ Yes	—
`offset`	int (long)	No	`0`
`count`	int (long)	No	— (reads to EOF)

Missing path → CFG_MISSING_PATH. Response: { mfsPath, size, data } — data is the raw byte[].

remove

Field	Type	Required	Default
`mfsPath`	text	✓ Yes	—
`recursive`	bool	No	`false` — required for non-empty directories
`force`	bool	No	`false` — treat "not found" as a no-op success

Missing path → CFG_MISSING_PATH. Response: { mfsPath }.

MFS root is protected: removing path / is refused before any network call, independent of the Validate() check — the executor's error message is "Refusing to remove the MFS root path "/"."

stat

Field	Type	Required	Default
`mfsPath`	text	✓ Yes	—
`withLocal`	bool	No	`false` — more expensive; computes local pinning/size stats

Missing path → CFG_MISSING_PATH. Response: { mfsPath, cid, size, cumulativeSize, blocks, type, withLocality }.

write

Binary input.

Field	Type	Required	Default
`mfsPath`	text	✓ Yes	—
`inputDataKey`	text	No	`data`
`dataMode`	select	No	`base64` (or `text`)
`inlineContent`	text	No	— fallback content
`offset`	int (long)	No	`0`
`create`	bool	No	`true` — diverges from Kubo's own default of `false`
`truncate`	bool	No	`true` — "replace whole file" semantics by default
`parents`	bool	No	`true` — consistent with `makeDirectory`'s divergence
`count`	int (long)	No	— (writes all input bytes)
`rawLeaves`	bool	No	`false`
`cidVersion`	int	No	`0`
`hashFunction`	text	No	`sha2-256`

Missing path → CFG_MISSING_PATH. Bytes resolved from InputData[inputDataKey] first, else inlineContent decoded per dataMode; empty → MISSING_FILE_DATA, bad base64 → INVALID_FILE_DATA_ENCODING. Response: { mfsPath, bytesWritten } — Kubo returns no CID for this call; bytesWritten is computed client-side from the input length.

Sensible defaults for building files incrementally: write and makeDirectory both default parents to true, and write defaults create/truncate to true — so a straightforward "write this file, creating any missing directories" call needs no extra flags.