Docly Developers
Function Updated 25 Oct 2026

listFiles(path, [options])

The fastest function to retrieve a list of files from a specific path.

See also getFiles listFolders GetFiles and Folders - examples getTags addTag getAllTags Path traversal Example: Fix unique ROWID values in a site

Parameters

pathstringrequired

Folder path to get list of files from. An empty string or null means the site root, the same as in getFiles, getFolders and listFolders.

optionsobjectoptional
Specify any of the following options parameters:
namestring

Wildcard for search, default is *. If not specified, all files will be returned.

tagsbool

Retrieve tags. Default "false", specify "true" to retrieve tags. Not to be confused with tag below — tags decides whether the tags come with the result, tag filters on them.

recursivebool

Return files from all subfolders also. If not specified, default is "false".

metaOnlybool

Do not return values for files. If not specified, default is "false".

schemastring

Wildcard for the schema name, default is "*". Pass an empty string to get only schemaless files.

filterobject

Property filter object (e.g. { "Status": "active" }). Each value is compared with the stored value as text, and the wildcards abc*, *abc and *abc* work.

tagstring

Only return files carrying this tag. The value is normalized exactly as tags are when they are stored, so "Invoice" finds the stored tag invoice. A value of several words requires all of them, and a value that normalizes to nothing (a single character, punctuation only) returns an empty result rather than everything. Filtering happens in the database, not on the returned array. See addTag.

Returns

An array of objects with Id, Guid, Name (with extension), Values, Modified, Schema, ModifiedBy (email) and Path. With tags: true each object also has Tags.

Values is the stored data as a JSON string — use JSON.parse to read it. It is null with metaOnly: true. Path is relative to the folder you asked for, and is only set when recursive is true.

Unlike getFiles, listFiles includes index.* files; folder properties files are left out. Files in folders the site's publisher has no website (Visit) access to are left out, and so are files inside # folders below the folder you asked for — the same rules as getFiles. Access is that of the user who published the site — the user the site runs as — not of the visitor, so the result is the same for everyone. To tailor a list to the signed-in visitor in an API script, check each item with allowVisit. An unknown folder, or a folder the site's publisher has no website (Visit) access to, gives an empty array; a path containing .. or a backslash gives null.

Example

Mixed HTML (or any text file) with inline JavaScript between hash signs.
#{
    /* Get all files starting with "example" */
    let options = { name : "example*" };
    let files = docly.listFiles("/Test files", options);
    
    /* List all files */
    for(let file of files)
    {
        var json = JSON.stringify(file);
        var html = JSON.format(json).replace(chr(13), "");
        write(html);
        write(chr(13) + "-----------------------------" + chr(13));
    }
}#