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 file as data.

Reads the contents of the file specified by the file path.

read(filePath: string): Data

-readString

Read contents of file as string.

The function serves as a shorthand for readString(filePath). For more information, see the documentation for readString(filePath).

readString(filePath: string): string

-readImage

Read contents of file as an image.

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

readImage(filePath: string): Image

-write

Write data to file.

write(filePath: string, content: Data)

-writeString

Write string to 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 image to 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.

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.

addTag(filePath: string, tag: string)

-removeTag

Removes a tag from a file.

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.

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.

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.

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