Changelog

Eagle Plugin API changelog, documenting all important feature changes since the first Plugin API version.

Update: Eagle 4.0 Build12 has been officially released. Features marked "Eagle 4.0 Build12+" are now available. If you are on an older version, please upgrade to 4.0 build12 or later.

March 24, 2026

📄 Item API Enhancement

New Feature: Comment CRUD API (Eagle 4.0 build22+)

Version Requirement: This feature requires Eagle 4.0 build22 or later.

• Added item.comments read-only property to access item comments/annotations

• Added item.addComment(commentData) method for adding image rect comments or video timestamp comments

• Added item.updateComment(commentId, updateData) method for updating existing comments

• Added item.removeComment(commentId) method for removing comments

let item = await eagle.item.getById('item_id');

// Read comments
console.log(item.comments);

// Add image rect comment
await item.addComment({ x: 350, y: 480, width: 380, height: 400, annotation: "Face area" });

// Add video timestamp comment
await item.addComment({ duration: 65.5, annotation: "Important scene" });

// Update comment
await item.updateComment('comment_id', { annotation: "Updated text" });

// Remove comment
await item.removeComment('comment_id');

📁 Smart Folder API

New Feature: Smart Folder CRUD API (Eagle 4.0 build22+)

Version Requirement: This feature requires Eagle 4.0 build22 or later.

• Added eagle.smartFolder module with full smart folder management support

• Added create(), get(), getAll(), getById(), getByIds(), remove() methods

• Added getRules() method to get available filter rule schema

• Added rule() fluent builder and Condition.create() helper

• SmartFolder instances support save() and getItems() methods

// Using the fluent builder
const sf = await eagle.smartFolder.create({
    name: 'Large Images',
    conditions: [
        eagle.smartFolder.Condition.create('AND', [
            eagle.smartFolder.rule('width')['>']([1920]),
            eagle.smartFolder.rule('type').equal('png'),
        ])
    ]
});

// Query rule schema
const rules = await eagle.smartFolder.getRules();

// Get matching items
const items = await sf.getItems();

🔧 Manifest Configuration Enhancement

New Feature: followCursor Window Positioning (Eagle 4.0 build22+)

Version Requirement: This feature requires Eagle 4.0 build22 or later.

• Added followCursor manifest setting — when enabled, the window automatically positions near the cursor

• Ideal for tool-type plugins that require quick interaction, minimizing the distance for user interaction

• When enabled, the window does not remember its position and follows the cursor each time it opens

{
    "main": {
        "followCursor": true
    }
}

January 22, 2026

💻 App API Enhancement

New Feature: Show Main Window (Eagle 4.0 build18+)

Version Requirement: This feature requires Eagle 4.0 build18 or later.

• Added eagle.app.show() method, allowing plugins to bring the Eagle main application window to the front and display it on top

// Bring Eagle main window to the front
await eagle.app.show();

📄 Item API Enhancement

New Feature: Modify Import Time (Eagle 4.0 build18+)

Version Requirement: This feature requires Eagle 4.0 build18 or later.

• item.importedAt property now supports modification, allowing plugins to customize file import time

• Useful for batch importing historical files, data migration, and other scenarios requiring preservation of original timestamps

// Modify import time
item.importedAt = new Date('2024-01-01').getTime();
await item.save();

January 9, 2026

🔍 AI Search Semantic Search API

New Feature: AI Semantic Search Integration (Eagle 4.0 build18+)

• Added eagle.extraModule.aiSearch module, providing AI semantic search capabilities

• Status Query Methods:

  • isInstalled() - Check if AI Search plugin is installed

  • isReady() - Check if service is ready

  • isStarting() - Check if service is starting

  • isSyncing() - Check if data is syncing

• Service Control Methods:

  • open() - Open AI Search plugin

  • checkServiceHealth() - Check service health status

  • getSyncStatus() - Get detailed sync status

• Search Methods:

  • searchByText(query, options) - Text semantic search

  • searchByBase64(base64, options) - Base64 image search

  • searchByItemId(itemId, options) - Search similar images by item ID

const aiSearch = eagle.extraModule.aiSearch;

// Check service status
if (await aiSearch.isReady()) {
    // Text semantic search
    const result = await aiSearch.searchByText('an orange cat', { limit: 10 });

    // Results contain complete Item objects
    result.results.forEach(r => {
        console.log(`${r.item.name} - Similarity: ${(r.score * 100).toFixed(1)}%`);
    });
}

January 8, 2026

🏷️ TagGroup/Tag API Incremental Operations

New Feature: Incremental Tag Group Operations (Eagle 4.0 build18+)

• tagGroup.addTags() - Incrementally add or move tags to a group without passing the complete tags array

• tagGroup.removeTags() - Remove specified tags from a group

• eagle.tag.merge() - Merge tags by renaming source tag to target tag

// Add tags to group
await tagGroup.addTags({ tags: ['UI', 'UX'] });

// Move tags (remove from original groups)
await tagGroup.addTags({ tags: ['Branding'], removeFromSource: true });

// Remove tags from group
await tagGroup.removeTags({ tags: ['Outdated'] });

// Merge tags
const result = await eagle.tag.merge({ source: 'UI Design', target: 'UI' });

🏷️ TagGroup API Enhancement

New Feature: Tag Group Description Property (Eagle 4.0 build18+)

• Added description property to tagGroup, allowing you to add descriptive text to tag groups

• Supported in both create() and save() methods

// Create a tag group with description
await eagle.tagGroup.create({
    name: "new group",
    description: "Group description"
});

// Modify tag group description
tagGroup.description = "New description";
await tagGroup.save();

January 6, 2026

🏷️ Tag API Enhancement

New Feature: Get Starred Tags (Eagle 4.0 build18+)

• Added eagle.tag.getStarredTags() method to retrieve user's favorite/starred tags

const starred = await eagle.tag.getStarredTags();

Documentation Fix

• Fixed incorrect API method name: getRecents() → getRecentTags()

August 21, 2025

💻 App API Enhancement

New Feature: app.userDataPath Property (Eagle 4.0 build12+)

• Added app.userDataPath property, returns the path to the current user data directory

• Provides quick access to Eagle's user data storage location

console.log(eagle.app.userDataPath);
// "C:\Users\User\AppData\Roaming\Eagle"

August 19, 2025

📁 Folder API Enhancements

New Feature: Folder parent Property Modifiable (Eagle 4.0 build12+)

• Added folder.parent property modification support, allowing dynamic adjustment of folder hierarchy

• Support for moving folders to different parent directories or root directory

// Move to another parent folder
folder.parent = 'parent_folder_id';
await folder.save();

// Move to root directory  
folder.parent = null;
await folder.save();

New Feature: Folder iconColor Property Modifiable (Eagle 4.0 build12+)

• Changed folder.iconColor property from read-only to modifiable

• Added eagle.folder.IconColor static constant object, providing predefined color options

• Supported colors: Red, Orange, Yellow, Green, Aqua, Blue, Purple, Pink

folder.iconColor = eagle.folder.IconColor.Blue;
await folder.save();

August 13, 2025

🏷️ Tag API Feature Expansion

New Feature: Tag Filtering and Tag Class Enhancement

• eagle.tag.get() method added name parameter, supporting fuzzy search by tag name

• Tag instance added save() method, supporting tag name modification

• Added Tag instance properties: name (modifiable), count, color, groups, pinyin

// Filter tags
const filteredTags = await eagle.tag.get({ name: "design" });

// Modify tag name  
tag.name = 'new-name';
await tag.save();

⚠️ Note: Modifying tag names will automatically update all files using that tag

August 5, 2025

📄 Item API Performance and Selection Enhancements

New Feature: Performance Optimization

• eagle.item.get() added fields parameter, supporting selective field return for significant query performance improvement

• Added eagle.item.getIdsWithModifiedAt() method, optimized for incremental synchronization

• Added modifiedAt property, recording file last modification time

// Return only needed fields
let items = await eagle.item.get({
    tags: ["Design"],
    fields: ["id", "name", "tags", "modifiedAt"]
});

// Efficient incremental sync
let fileInfo = await eagle.item.getIdsWithModifiedAt();

New Feature: Counting and Selection Methods

• Added eagle.item.count(options) - conditional counting

• Added eagle.item.countAll() - total file count

• Added eagle.item.countSelected() - selected file count

• Added eagle.item.select(itemIds) - programmatic file selection

let count = await eagle.item.count({ isSelected: true });
await eagle.item.select(['ITEM_ID_1', 'ITEM_ID_2']);

Enhanced Feature: open() Method

• eagle.item.open() added window option, supporting opening files in new window

await eagle.item.open('item_id', { window: true });

July 31, 2025

🪟 Window API Expansion

New Feature: Window Geometry Control

• Added eagle.window.getSize() - get window size

• Added eagle.window.setBounds(bounds) - set window bounds (position + size)

• Added eagle.window.getBounds() - get window bounds information

await eagle.window.getSize();
await eagle.window.setBounds({ x: 440, y: 225, width: 800, height: 600 });
await eagle.window.getBounds();

November 28, 2024

🏷️ TagGroup CRUD Operations

New Feature: Complete Tag Group Management

• Added eagle.tagGroup.create(options) - create new tag group

• Added tagGroup.save() - save modifications

• Added tagGroup.remove() - delete tag group

// Create tag group
await eagle.tagGroup.create({
    name: "new group",
    color: "red", 
    tags: ["tag1", "tag2"]
});

// Modify and save
tagGroup.name = "new name";
await tagGroup.save();

// Delete group
await tagGroup.remove();

🗑️ Item Deletion Feature

New Feature: File Trash Operations

• Added item.moveToTrash() instance method, moving files to system trash

let item = await eagle.item.getById('item_id');
await item.moveToTrash();

July 25, 2024

🪟 Window API Enhancement

New Feature: HTTP Referer Setting

• Added eagle.window.setReferer(url) method, setting referer header for subsequent network requests

eagle.window.setReferer("https://example.com");

May 10, 2024

🖱️ Context Menu API

New Feature: Custom Context Menu

• Added eagle.contextMenu.open() method, supporting custom context menus

• Support for multi-level submenus, custom click events, system native styling

eagle.contextMenu.open([
    {
        id: "edit",
        label: "Edit",
        submenu: [...],
        click: () => { ... }
    }
]);

🪟 Window API Screenshot Feature

New Feature: Page Screenshot

• Added eagle.window.capturePage(rect) method, supporting full page or specified area screenshots

• Returns NativeImage object, convertible to base64 or PNG buffer

// Full page screenshot
const image = await eagle.window.capturePage();

// Specified area screenshot
const image2 = await eagle.window.capturePage({ 
    x: 0, y: 0, width: 100, height: 50 
});

April 17, 2024

🔍 Preview Plugin Feature Enhancement

New Feature: Zoom Control Parameter

• Preview plugin configuration added allowZoom parameter, controlling whether users can zoom preview content

"thumbnail": {
    "path": "thumbnail/icns.js",
    "size": 400,
    "allowZoom": false
}