Skip to content

FileManager

Read and write files on disk.

A FileManager lets you read files stored on the disk and make changes to them. Paths to files are supplied as strings.

+local

Creates a local FileManager.

Creates a file manager for operating with files stored locally.

static local(): FileManager

+iCloud

Creates an iCloud FileManager.

Creates a file manager for operating with files stored in iCloud. iCloud must be enabled on the device in order to use this.

static iCloud(): FileManager

-read

Read contents of a file as data.

Reads the contents of the file specified by the file path as raw data. To read the file as a string see readString(filePath) and to read it as an image see readImage(filePath).

The function will error if the file does not exist or if it exists in iCloud but have not been download. Use fileExists(filePath) to check if a file exists and downloadFileFromiCloud(filePath) to download the file. Note that it is always safe to call downloadFileFromiCloud(filePath), even if the file is stored locally on the device.

read(filePath: string): Data

-readString

Read contents of a file as string.

The function will error if the file does not exist or if it exists in iCloud but have not been download. Use fileExists(filePath) to check if a file exists and downloadFileFromiCloud(filePath) to download the file. Note that it is always safe to call downloadFileFromiCloud(filePath), even if the file is stored locally on the device.

readString(filePath: string): string

-readImage

Read contents of a file as an image.

Reads the contents of the file specified by the file path and convert it to an image.

The function will error if the file does not exist or if it exists in iCloud but have not been download. Use fileExists(filePath) to check if a file exists and downloadFileFromiCloud(filePath) to download the file. Note that it is always safe to call downloadFileFromiCloud(filePath), even if the file is stored locally on the device.

readImage(filePath: string): Image

-write

Write data to a file.

write(filePath: string, content: Data)

-writeString

Write a string to a file.

Writes the content to the specified file path on disk. If the file does not already exist, it will be created. If the file already exists the contents of the file will be overwritten with the new content.

writeString(filePath: string, content: string)

-writeImage

Write an image to a file.

Writes the image to the specified file path on disk. If the file does not already exist, it will be created. If the file already exists the contents of the file will be overwritten with the new content.

writeImage(filePath: string, image: Image)

-remove

Removes a file.

Removes the file at the specified path. Use with caution. Removed files cannot be restored.

remove(filePath: string)

-move

Moves a file.

Moves the file from the source path to the destination path. Caution: This operation will replace any existing file at the the destination.

move(sourceFilePath: string, destinationFilePath: string)

-copy

Copies a file.

Copies the file from the source path to the destination path. Caution: This operation will replace any existing file at the the destination.

copy(sourceFilePath: string, destinationFilePath: string)

-fileExists

Checks if a file exists.

Checks if the file exists at the specified file path. Checking this before moving or copying to a destination can be a good idea as those operations will replace any existing file at the destination file path.

fileExists(filePath: string): bool

-isDirectory

Checks if a path points to a directory.

isDirectory(path: string): bool

-createDirectory

Creates a directory at the specified path.

You can optionally create all intermediate directories.

createDirectory(path: string, intermediateDirectories: bool)

-temporaryDirectory

Path of temporary directory.

Used to retrieve the path of a temporary directory on disk. The operating system may at anytime delete files stored in this directory and therefore you should not rely on it for long time storage. If you need long time storage, see documentsDirectory() or libraryDirectory(). This directory is not shared between the app, the action extension and Siri.

temporaryDirectory(): string

-documentsDirectory

Path of documents directory.

Used to retrieve the path to the documents directory. Your scripts are stored in this directory. If you have iCloud enabled, your scripts will be stored in the documents directory in iCloud otherwise they will be stored in the local documents directory. The directory can be used for long time storage. Documents stored in this directory can be accessed using the Files app. Note that files stored in the local documents directory will not appear in the Files app unless you enable the "Scriptable Local" file provider. Visit the Files app to enable the file provider.

documentsDirectory(): string

-libraryDirectory

Path of library directory.

Used to retrieve the path to the documents directory. The directory can be used for long time storage. Documents stored in this directory cannot be accessed using the Files app.

libraryDirectory(): string

-joinPath

Joins two path components.

Joins two paths to created one path. For example to join the path to a directory with the name of a file. This is the suggested approach for creating new file paths passed to the read and write functions of a FileManager.

joinPath(lhsPath: string, rhsPath: string): string

-allTags

Reads all tags from a file.

The tags are written from the file at the specified path. Tags can either be read added and removed using the Files app or using the APIs provided by a FileManager.

The function will error if the file does not exist or if it exists in iCloud but have not been download. Use fileExists(filePath) to check if a file exists and downloadFileFromiCloud(filePath) to download the file. Note that it is always safe to call downloadFileFromiCloud(filePath), even if the file is stored locally on the device.

allTags(filePath: string): [string]

-addTag

Adds a tag to a file.

A tag can only be added to a file once. It is not possible to specify a color for the tag. You can create the tags using the Files app to specify the color and the add them to files afterwards using the FileManager API.

The function will error if the file does not exist or if it exists in iCloud but have not been download. Use fileExists(filePath) to check if a file exists and downloadFileFromiCloud(filePath) to download the file. Note that it is always safe to call downloadFileFromiCloud(filePath), even if the file is stored locally on the device.

addTag(filePath: string, tag: string)

-removeTag

Removes a tag from a file.

The function will error if the file does not exist or if it exists in iCloud but have not been download. Use fileExists(filePath) to check if a file exists and downloadFileFromiCloud(filePath) to download the file. Note that it is always safe to call downloadFileFromiCloud(filePath), even if the file is stored locally on the device.

removeTag(filePath: string, tag: string)

-readExtendedAttribute

Reads an extended attribute from a file.

Extended attributes are metadata that can be stored on a file. Note that extended attributes are not synced with iCloud.

The function will return null if the attribute does not exist.

The function will error if the file does not exist or if it exists in iCloud but have not been download. Use fileExists(filePath) to check if a file exists and downloadFileFromiCloud(filePath) to download the file. Note that it is always safe to call downloadFileFromiCloud(filePath), even if the file is stored locally on the device.

readExtendedAttribute(filePath: string, name: string): string

-writeExtendedAttribute

Writes an extended attribute to a file.

Extended attributes are metadata that can be stored on a file. Note that extended attributes are not synced with iCloud.

The function will error if the file does not exist or if it exists in iCloud but have not been download. Use fileExists(filePath) to check if a file exists and downloadFileFromiCloud(filePath) to download the file. Note that it is always safe to call downloadFileFromiCloud(filePath), even if the file is stored locally on the device.

writeExtendedAttribute(filePath: string, value: string, name: string)

-removeExtendedAttribute

Removes an extended attribute from a file.

Extended attributes are metadata that can be stored on a file. Note that extended attributes are not synced with iCloud.

The function will error if the file does not exist or if it exists in iCloud but have not been download. Use fileExists(filePath) to check if a file exists and downloadFileFromiCloud(filePath) to download the file. Note that it is always safe to call downloadFileFromiCloud(filePath), even if the file is stored locally on the device.

removeExtendedAttribute(filePath: string, name: string)

-allExtendedAttributes

Reads all extended attributes on a file.

Extended attributes are metadata that can be stored on a file. Note that extended attributes are not synced with iCloud.

allExtendedAttributes(filePath: string): [string]

-getUTI

Gets the UTI of the specified file.

The Uniform Type Identifier is a string that identifies the type of file.

getUTI(filePath: string): string

-listContents

Lists content of directory.

Lists all the contents in the specified directory. The returned array contains file paths to all files in the directory.

listContents(directoryPath: string): [string]

-fileName

Get name of a file.

Takes a file path and returns the name of the file. Also supports getting the name of a directory. The returned file name optionally includes the extension of the file.

fileName(filePath: string, includeFileExtension: bool): string

-fileExtension

Get extension of a file.

Takes a file path and returns the extension of the file, e.g. ".jpg" or ".js". Returns en empty string for directories.

fileExtension(filePath: string): string

-bookmarkedPath

Get path to a bookmarked file or folder.

Gets the path to a bookmarked file or filder. Use file bookmarks to access files and folders outside Scriptables documents directory.

You can edit your file bookmarks from Scriptables settings.

The function will throw an error if no bookmark exists.

Please be aware that bookmarks can only be used in the app. All APIs that relate to bookmarks will always throw an error when used in Siri or in a script run from the Share Sheet.

bookmarkedPath(name: string): string

-bookmarkExists

Check if a bookmark exists.

Checks if a file bookmark exists with the specified name.

You can edit your file bookmarks from Scriptables settings.

Please be aware that bookmarks can only be used in the app. All APIs that relate to bookmarks will always throw an error when used in Siri or in a script run from the Share Sheet.

bookmarkExists(name: string): bool

-downloadFileFromiCloud

Download file from iCloud if necessary.

Downloads the file from iCloud if it have not already been downloaded. If you pass in a path to a file that is not stored in iCloud, the returned will be resolved immediately making it safe to pass in any file path.

downloadFileFromiCloud(filePath: string): Promise

-isFileStoredIniCloud

Checks if a file is stored in iCloud.

Checks if a file is stored in iCloud or locally on the device. The function returns false if the file does not exist. Check if a file exists using fileExists(filePath)

isFileStoredIniCloud(filePath: string): bool

-isFileDownloaded

Checks if a file have been downloaded.

If a file is stored in iCloud and have not been downloaded, this function returns false. In that case, the file can be downloaded using downloadFileFromiCloud(filePath. If the file is not stored in iCloud but rather locally on the device, this function returns true.

The function returns false if the file does not exist. Check if a file exists using fileExists(filePath)

isFileDownloaded(filePath: string): bool