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.

static local(): FileManager

Creates a file manager for operating with files stored locally.

Return value

FileManager
Local FileManager.


+iCloud

Creates an iCloud FileManager.

static 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.

Return value

FileManager
iCloud FileManager.


-read

Read contents of a file as data.

read(filePath: string): 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.

Parameters

filePath
string
Path of the file to read.

Return value

Data
Contents of the file as a data or null if the file could not be read.


-readString

Read contents of a file as string.

readString(filePath: string): 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.

Parameters

filePath
string
Path of the file to read.

Return value

string
Contents of the file as a string or null if the file could not be read.


-readImage

Read contents of a file as an image.

readImage(filePath: string): 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.

Parameters

filePath
string
Path of the file to read.

Return value

Image
Contents of the file as an image or null if the file could not be read.


-write

Write data to a file.

write(filePath: string, content: Data)

Parameters

filePath
string
Path of file to write to.

content
Data
Data to write to disk.


-writeString

Write a string to a file.

writeString(filePath: string, content: string)

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.

Parameters

filePath
string
Path of file to write to.

content
string
Content to write to disk.


-writeImage

Write an image to a file.

writeImage(filePath: string, image: Image)

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.

Parameters

filePath
string
Path of file to write to.

image
Image
Image to write to disk.


-remove

Removes a file.

remove(filePath: string)

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

Parameters

filePath
string
Path of file to remove.


-move

Moves a file.

move(sourceFilePath: string, destinationFilePath: string)

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

Parameters

sourceFilePath
string
Path of the file to move.

destinationFilePath
string
Path to move the file to.


-copy

Copies a file.

copy(sourceFilePath: string, destinationFilePath: string)

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

Parameters

sourceFilePath
string
Path of the file to copy.

destinationFilePath
string
Path to copy the file to.


-fileExists

Checks if a file exists.

fileExists(filePath: string): bool

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.

Parameters

filePath
string
File path to examine.

Return value

bool
True if the file exists otherwise false.


-isDirectory

Checks if a path points to a directory.

isDirectory(path: string): bool

Parameters

path
string
Path to examine.

Return value

bool
True if the path points to a directory otherwise false.


-createDirectory

Creates a directory at the specified path.

createDirectory(path: string, intermediateDirectories: bool)

You can optionally create all intermediate directories.

Parameters

path
string
Path of directory to create.

intermediateDirectories
bool
Whether to create all intermediate directories. Defaults to false.


-temporaryDirectory

Path of temporary directory.

temporaryDirectory(): string

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.

Return value

string
Path to temporary directory.


-documentsDirectory

Path of documents directory.

documentsDirectory(): string

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.

Return value

string
Path to documents directory.


-libraryDirectory

Path of library directory.

libraryDirectory(): string

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.

Return value

string
Path to library directory.


-joinPath

Joins two path components.

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

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.

Parameters

lhsPath
string
Left-hand side part of the new path.

rhsPath
string
Right-hand side part of the new path.

Return value

string
Path with the two path components joined.


-allTags

Reads all tags from a file.

allTags(filePath: string): [string]

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.

Parameters

filePath
string
Path of file to read tags from.

Return value

[string]
Read tags.


-addTag

Adds a tag to a file.

addTag(filePath: string, tag: string)

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.

Parameters

filePath
string
Path of file to add the tag to.

tag
string
Tag to add. This can be an existing tag or a new tag.


-removeTag

Removes a tag from a file.

removeTag(filePath: string, tag: 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.

Parameters

filePath
string
Path of file to remove the tag from.

tag
string
Tag to remove.


-readExtendedAttribute

Reads an extended attribute from a file.

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

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.

Parameters

filePath
string
Path of file to read extended attribute from.

name
string
Name of the extended attribute to read.

Return value

string
Value of the extended attribute.


-writeExtendedAttribute

Writes an extended attribute to a file.

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

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.

Parameters

filePath
string
Path of file to add an extended attribute to.

value
string
Value of the extended attribute.

name
string
Name of the extended attribute. This is used to retrieve the value at a later point.


-removeExtendedAttribute

Removes an extended attribute from a file.

removeExtendedAttribute(filePath: string, name: string)

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.

Parameters

filePath
string
Path of file to add an extended attribute to.

name
string
Name of the extended attribute to remove.


-allExtendedAttributes

Reads all extended attributes on a file.

allExtendedAttributes(filePath: string): [string]

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

Parameters

filePath
string
Path of file to read extended attributes from.

Return value

[string]
An array of all extended attributes.


-getUTI

Gets the UTI of the specified file.

getUTI(filePath: string): string

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

Parameters

filePath
string
Path of file to get UTI of.

Return value

string
The UTI of the file.


-listContents

Lists content of directory.

listContents(directoryPath: string): [string]

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

Parameters

directoryPath
string
Path to directory.

Return value

[string]
File paths to all files in the directory.


-fileName

Get name of a file.

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

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.

Parameters

filePath
string
path of file to get name of.

includeFileExtension
bool
Whether or not the file extension should be included. Defaults to false.

Return value

string
Name of the file.


-fileExtension

Get extension of a file.

fileExtension(filePath: string): string

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

Parameters

filePath
string
Path of file to get extension from.

Return value

string
Extension of the file.


-bookmarkedPath

Get path to a bookmarked file or folder.

bookmarkedPath(name: string): string

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.

Parameters

name
string
Name of bookmark to create path for.

Return value

string
Path to the bookmarked file or folder.


-bookmarkExists

Check if a bookmark exists.

bookmarkExists(name: string): bool

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.

Parameters

name
string
Name of bookmark.

Return value

bool
True of a bookmark exists for the specified name, otherwise false.


-downloadFileFromiCloud

Download file from iCloud if necessary.

downloadFileFromiCloud(filePath: string): Promise

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.

Parameters

filePath
string
Path of file to download from iCloud.

Return value

Promise
Promise that is fulfilled when the file have been downloaded.


-isFileStoredIniCloud

Checks if a file is stored in iCloud.

isFileStoredIniCloud(filePath: string): bool

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)

Parameters

filePath
string
Path of file.

Return value

bool
True if the file is stored in iCloud otherwise false.


-isFileDownloaded

Checks if a file have been downloaded.

isFileDownloaded(filePath: string): bool

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)

Parameters

filePath
string
Path of file.

Return value

bool
True if the file have been downloaded otherwise false.