# tag

```javascript
// Get all tags
const tags = await eagle.tag.get();

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

// Get recently used tags
const recents = await eagle.tag.getRecentTags();

// Get starred tags
const starred = await eagle.tag.getStarredTags();
```

## Methods <a href="#z1a5y" id="z1a5y"></a>

## get(options) <a href="#x9nu2" id="x9nu2"></a>

Retrieves tags with optional filtering.

* `options` Object (optional) - Query conditions
  * `name` string (optional) - Filter tags by name with fuzzy search, case-insensitive
* Returns `Promise<tags: Object[]>` - the query result for tags.

```javascript
// Get all tags
const tags = await eagle.tag.get();

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

{% hint style="info" %}
Note: The `name` parameter requires Eagle 4.0 build12 or higher.
{% endhint %}

***

## getRecentTags() <a href="#dwsxw" id="dwsxw"></a>

Retrieves the most recently used tags.

* Returns `Promise<tags: Object[]>` - the query result for tags.

```javascript
const recents = await eagle.tag.getRecentTags();
```

***

## getStarredTags() <a href="#starred" id="starred"></a>

Retrieves starred tags (user's favorite tags).

* Returns `Promise<tags: Object[]>` - the query result for tags.

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

{% hint style="info" %}
Note: The `getStarredTags()` method requires Eagle 4.0 build18 or higher.
{% endhint %}

***

## merge(options) <a href="#merge" id="merge"></a>

Merges tags: renames the source tag to the target tag, automatically updating all items using the source tag.

* `options` Object - Option parameters
  * `source` string - Source tag name (will be removed)
  * `target` string - Target tag name (will be kept after merge)
* Returns `Promise<Object>` - Merge result
  * `affectedItems` number - Number of affected items
  * `sourceRemoved` boolean - Whether the source tag was removed

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

console.log(`Merged tags for ${result.affectedItems} items`);
```

{% hint style="info" %}
Note: The `merge()` method requires Eagle 4.0 build18 or higher.
{% endhint %}

{% hint style="warning" %}
Warning: The merge operation updates all items, tag groups, starred tags, and history tags that use the source tag. This operation is irreversible.
{% endhint %}

***

## Class: Tag <a href="#tag-class" id="tag-class"></a>

Object type returned by Eagle API `get`, providing modification and save functionality.

{% hint style="success" %}
**🦄 Best Practice:** To ensure data security, use the `save()` method provided by the Tag instance to modify data. Avoid directly modifying tag data in the Eagle resource library.
{% endhint %}

***

### Instance Methods <a href="#instance-methods" id="instance-methods"></a>

#### **save()**

Save tag modifications. Currently only supports modifying tag names.

* Returns `Promise<result: boolean>` - `result` whether the modification was successful

```javascript
// Get all tags
const tags = await eagle.tag.get();

// Find the tag to modify
const tag = tags.find(t => t.name === 'old-name');

// Modify tag name
tag.name = 'new-name';

// Save changes
await tag.save();
```

{% hint style="info" %}
Note: The `save()` method requires Eagle 4.0 build12 or higher.
{% endhint %}

{% hint style="warning" %}
Warning: After modifying a tag name, all files using that tag will automatically be updated with the new tag name.
{% endhint %}

***

### Instance Properties <a href="#instance-properties" id="instance-properties"></a>

#### **`name` string**

Tag name. This property can be modified and saved through the `save()` method.

#### **`count` number**

Read-only, number of files using this tag.

#### **`color` string**

Tag color.

#### **`groups` string\[]**

Read-only, groups the tag belongs to.

#### **`pinyin` string**

Read-only, pinyin of tag name (for search and sorting).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.eagle.cool/plugin-api/api/tag.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.