app.xattr - Extended Attributes & Finder Tags API

File extended attributes (xattr) and Finder tags/comments operations.

Extended Attributes

app.xattr.get(path, name)

Get an extended attribute value.

Parameters:

• path (string) - file path
• name (string) - attribute name

Returns: string, error - attribute value (UTF-8 or Base64 encoded), returns nil, error on failure

local value, err = app.xattr.get("/path/to/file", "com.example.custom")

app.xattr.set(path, name, value)

Set an extended attribute.

Parameters:

• path (string) - file path
• name (string) - attribute name
• value (string) - attribute value

Returns: boolean, error

local ok, err = app.xattr.set("/path/to/file", "com.example.custom", "my value")

app.xattr.list(path)

List all extended attribute names.

Parameters:

• path (string) - file path

Returns: array<string>, error

local names, err = app.xattr.list("/path/to/file")
for _, name in ipairs(names) do
    app.log.info("xattr: " .. name)
end

app.xattr.remove(path, name)

Remove an extended attribute.

Parameters:

• path (string) - file path
• name (string) - attribute name

Returns: boolean, error

local ok, err = app.xattr.remove("/path/to/file", "com.example.custom")

Finder Tags

app.xattr.getTags(path)

Get the Finder tags of a file.

Parameters:

• path (string) - file path

Returns: array<string>, error - array of tag names, returns nil, error on failure

local tags = app.xattr.getTags("/path/to/file")
-- {"Important", "Work"}

app.xattr.setTags(path, tags)

Set Finder tags for a file (full replacement).

Parameters:

• path (string) - file path
• tags (array) - array of tag names

Returns: boolean, error

app.xattr.setTags("/path/to/file", {"Important", "Work"})

app.xattr.addTag(path, tag)

Add a single Finder tag (no duplicates).

Parameters:

• path (string) - file path
• tag (string) - tag name

Returns: boolean, error

app.xattr.addTag("/path/to/file", "Important")

app.xattr.removeTag(path, tag)

Remove a single Finder tag.

Parameters:

• path (string) - file path
• tag (string) - tag name

Returns: boolean, error

app.xattr.removeTag("/path/to/file", "Important")

Finder Comments

app.xattr.getComment(path)

Get the Finder comment of a file.

Parameters:

• path (string) - file path

Returns: string, error - comment content, returns nil, error on failure

local comment = app.xattr.getComment("/path/to/file")

app.xattr.setComment(path, comment)

Set the Finder comment of a file.

Parameters:

• path (string) - file path
• comment (string) - comment content

Returns: boolean, error

app.xattr.setComment("/path/to/file", "This is an important file")

Examples

Batch Add Tags

function MyPlugin:handleTagFiles(context)
    local result = app.dialog.input("Enter tag name")
    if not result then return end

    local count = 0
    for _, file in ipairs(context.selectedFiles) do
        local ok = app.xattr.addTag(file, result)
        if ok then count = count + 1 end
    end

    app.notification.show("Done", "Added tag '" .. result .. "' to " .. count .. " files")
end

View File Metadata

function MyPlugin:handleShowInfo(context)
    local file = context.selectedFiles[1]
    local tags = app.xattr.getTags(file)
    local comment = app.xattr.getComment(file) or ""
    local attrs = app.xattr.list(file) or {}

    local info = "Tags: " .. table.concat(tags, ", ") .. "\n"
    info = info .. "Comment: " .. comment .. "\n"
    info = info .. "Extended attributes count: " .. #attrs

    app.dialog.alert("File Info", info)
end