Reference
Arcane.filesystem.selectDirectory()
Opens the native directory picker after a user action. It returns one canonical existing directory or explicit cancellation; it does not enumerate or grant access to directory contents. Requires filesystem.directory.select.
This focused page is derived from the mechanically checked full member inventory.
Syntax
Arcane.filesystem.selectDirectory(options?)
Parameters
options?: {title?, initialPath?}; title up to 200 plain-text characters; initial path must be an existing absolute directory
Return value
Promise<{cancelled:boolean, path:string|null}>
Description
Opens the native directory picker after a user action. It returns one canonical existing directory or explicit cancellation; it does not enumerate or grant access to directory contents. Requires filesystem.directory.select.
Overview
Opens the operating system's folder picker after a user action and returns one canonical existing directory. This is a selection capability, not general filesystem access: it does not enumerate drives, read the directory, create a folder, or grant permission to its contents.
Use it when an application needs the user to choose a local workspace or export location. The application must still validate that the selected directory is appropriate for its own workflow.
Options
Pass an object containing only these optional fields:
| Field | Contract |
|---|---|
title |
Plain-text dialog title. Defaults to Choose a folder; maximum 200 characters; control characters are rejected. |
initialPath |
Existing absolute directory path. It is canonicalized before the picker opens and may not exceed 4,096 characters. |
The promise resolves to {cancelled:true,path:null} when the user cancels, or
{cancelled:false,path} with the canonical absolute path. Cancellation is a
normal result, not an error.
Availability and errors
Requires filesystem.directory.select. Core-backed Microsoft NT uses the native
folder browser; Linux uses an installed Zenity or KDialog picker. Unsupported
hosts reject with FILESYSTEM_DIRECTORY_SELECTION_UNSUPPORTED. Invalid options,
an unavailable initial path, an invalid host response, or a selected directory
that disappears are rejected explicitly.
Example
async function chooseWorkspaceDirectory() {
const access = await Arcane.capabilities.list();
if (!access.methods.includes('filesystem.directory.select')) return null;
const selection = await Arcane.filesystem.selectDirectory({
title: 'Choose a development workspace'
});
return selection.cancelled ? null : selection.path;
}
document.querySelector('#choose-workspace')?.addEventListener(
'click',
async function handleWorkspaceSelection() {
const path = await chooseWorkspaceDirectory();
if (path) document.querySelector('#workspace-path').textContent = path;
}
);