Work with files and folders
Use api.files for supported filesystem work. It provides cross-platform path helpers, typed directory listings, revision-aware text and binary writes, cancellable folder summaries, recoverable mutations, directory watches, and native reveal behavior. Pane-owned opening lives on api.explorer.
Filesystem access is permission-gated. A path supplied by a user or received from Phials is not itself an access grant. Your plugin manifest must request the permission required by the operation, and Phials must have access to that location through the operating system.
Choose the smallest permission
| Operation | Method | Permission |
|---|---|---|
| Inspect path strings | getExtension, getBasename, getDirname, joinPath | Always available |
| Ask the user for a folder | pickDirectory | Always available |
| List/summarize a folder, read text or bytes, inspect Git, or create an asset URL | readDirectory, getFolderSummary, readText, readBinary, api.git, toAssetUrl | filesystem.read |
| Watch a folder | watchDirectory | filesystem.read |
| Create, write, rename, or trash | writeText, writeBinary, createDirectory, renamePath, trash | filesystem.write |
| Open in Phials or reveal in the native file manager | pane.navigation.openPath, api.files.revealPath | Always available |
filesystem.write includes the supported read operations, so a plugin that reads and writes files requests only filesystem.write. Request filesystem.read when the plugin never changes filesystem content. See Request the least plugin permissions.
{
"permissions": ["filesystem.read"]
}Permissions gate the supported Plugin API. They do not make arbitrary filesystem locations portable or guarantee operating-system access. Do not use raw host commands, browser URLs, or imported native filesystem packages to bypass api.files.
Work through the tasks
- Work with paths and file entries
- Let users choose and read folders
- Read and write text files safely
- Create, rename, and trash files and folders
- Watch folders for changes
- Open and reveal files and folders
Keep ownership clear
api.files performs one requested operation. Your plugin still owns:
- deciding why the operation is necessary
- asking for confirmation before consequential changes
- retaining revision tokens between a read and write
- representing partial failures without claiming the whole batch succeeded
- releasing watches when their feature is no longer active
- explaining permission or operating-system errors in user-facing terms
Phials owns:
- permission enforcement and the approved host-command allowlist
- cross-platform path and Trash behavior
- atomic text and binary replacement with one conflict contract
- file-opening policy and native file-manager integration
- deactivation cleanup for retained watches
For binary content needed during metadata extraction, use the provider-specific metadata API described in Extract file metadata. General api.files text operations are deliberately UTF-8 only.