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 has 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 has 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 converts it to an image.
The function will error if the file does not exist or if it exists in iCloud but has 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. If a file already exists at the destination file path, the operation will fail and the file will not be copied.
Parameters¶
sourceFilePath
string
Path of the file to copy.
destinationFilePath
string
Path to copy the file to.
-fileExists¶
Checks if the 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. Data persisted in a temporary directory will generally live shorter than data persisted in the cache directory.
The operating system may at any time 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.
-cacheDirectory¶
Path of cache directory.
cacheDirectory(): string
Used to retrieve the path of a cache directory on disk. The operating system may at any time delete files stored in this directory and therefore you should not rely on it for long time storage.
Data persisted in the cache directory will generally live longer than data persisted in a temporary directory.
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. Files stored in the local documents directory will not appear in the Files app.
Return value¶
string
Path to documents directory.
-libraryDirectory¶
Path of library directory.
libraryDirectory(): string
Used to retrieve the path to the library 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 read from the file at the specified path. Tags can either be read, added and removed using the Files app by using the APIs provided by a FileManager.
The function will error if the file does not exist or if it exists in iCloud but has 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 then 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 has 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 has 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 has 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 has 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 has 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 filenames to all files and directories in the specified directory.
Parameters¶
directoryPath
string
Path to directory.
Return value¶
[string]
Names of all the files and directories in the specified 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 the bookmark doesn't exist.
Please beware that bookmarks created from Scriptables settings only can be used when running a script in the app and not from the Share Sheet, Siri and Shortcuts. If you wish to use a bookmark from Siri or the Shortcuts app, the bookmark must be created using Scriptables "Create File Bookmark" shortcut action using the Shortcuts app.
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 beware that bookmarks created from Scriptables settings only can be used when running a script in the app and not from the Share Sheet, Siri and Shortcuts. If you wish to use a bookmark from Siri or the Shortcuts app, the bookmark must be created using Scriptables "Create File Bookmark" shortcut action using the Shortcuts app.
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 promise 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 it has 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.
-creationDate¶
Reads the creation date of a file.
creationDate(filePath: string): Date
The returned value will be null if the creation date cannot be read.
Parameters¶
filePath
string
Path of file.
Return value¶
Date
The date the file was created.
-modificationDate¶
Reads the modification date of a file.
modificationDate(filePath: string): Date
The returned value will be null if the modification date cannot be read.
Parameters¶
filePath
string
Path of file.
Return value¶
Date
The date the file was last modified.
-fileSize¶
Size of the file in kilobytes.
fileSize(filePath: string): number
The returned value will be null if the file size cannot be read.
Parameters¶
filePath
string
Path of file.
Return value¶
number
The file size measured in kilobytes.
-allFileBookmarks¶
Reads all file bookmarks created in settings.
allFileBookmarks(): [{string: string}]
File bookmarks are used to bookmark a file or a folder and read or write to it later. File bookmarks are created from Scriptables settings.
This function returns all file bookmarks as an array of objects that take the following form.
{
"name": "My Bookmark",
"source": "host"
}
The source can either be host for file bookmarks that can be used in the app or siri_shortcuts for file bookmarks that can be used in Siri and Shortcuts.