Namespace fs

Module for filesystem operations. hs.fs provides a comprehensive set of filesystem operations covering file I/O, directory management, path manipulation, metadata access, symbolic links, Finder tags, and macOS-specific features like file bookmarks and Uniform Type Identifiers. It replaces both Hammerspoon v1's hs.fs module and the functionality that was previously available through Lua's built-in io and file modules.

Reading and writing files

const contents = hs.fs.read("/etc/hosts");           // entire file
const chunk    = hs.fs.read("/etc/hosts", 100, 50);  // 50 bytes from offset 100

hs.fs.eachLine("/etc/hosts", function(line) {
   console.log(line);
   // return false to stop early
});

hs.fs.write("/tmp/hello.txt", "Hello, world!\n");
hs.fs.append("/tmp/hello.txt", "More content\n");

Working with open files

For incremental, positioned, binary, or locked access, open the file to get an

const f = hs.fs.open("~/notes.txt", "r+");
const firstLine = f.readLine();
f.seek(0, "end");
f.writeLine("appended");
f.close();

// Or let hs.fs.withFile() close it for you:
const header = hs.fs.withFile("~/image.png", "r", f => f.readBytes(8));

Errors

Functions that fail return null or false and set hs.fs.lastError to an object like {code: "ENOENT", message: "No such file or directory"}. Most failures are also logged to the Console; failures that are often expected (such as hs.fs.open() on a missing file) are not.

Directory operations

hs.fs.mkdir("~/Projects/new-thing");

const files = hs.fs.list("~/Documents");
const all   = hs.fs.listRecursive("~/Documents");

Path utilities

const abs  = hs.fs.pathToAbsolute("~/Library");
const tmp  = hs.fs.tempDirectory();
const home = hs.fs.homeDirectory();

Metadata

const info = hs.fs.attributes("/etc/hosts");
// { size: 1234, type: "file", permissions: 420,
//   ownerID: 0, groupID: 0,
//   creationDate: 1700000000.0, modificationDate: 1700001000.0 }

Variables

lastError