# Eagle Add Item

> Add and verify one asset at a time in a locally running Eagle library using curl, with support for local paths, image URLs, Base64 images, and bookmarks. Use when the user invokes $eagle-add-item or asks to add, import, save, or register (追加・取り込み・保存・登録) an individual file, image, URL, or bookmark in Eagle. Repeated requests are handled sequentially with exact-name duplicate protection.

- Skill: `tuki0918/eagle-add-item` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tuki0918/eagle-add-item`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tuki0918/eagle-add-item/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tuki0918 (https://skillmd.com/u/tuki0918)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tuki0918/eagle-add-item

---


# Eagle Add Item

Use the bundled shell script to send one verified Eagle request at a time with `curl`. Do not use Python or Eagle batch-add endpoints.

## Workflow

1. Identify exactly one source:
   - Local file: `--path`
   - Image URL: `--url`
   - Base64 text file: `--base64-file`
   - Bookmark: `--bookmark-url`
2. Collect only metadata the user supplied: `name`, `tags`, one folder ID, `annotation`, and `website`.
3. Resolve the directory containing this `SKILL.md`.
4. Run `scripts/eagle_add.sh` without `--execute` and inspect the dry-run.
5. If the user asked to add, import, save, or register the item, rerun the same command with `--execute`.
6. Report the verified Eagle item ID.

For multiple items, repeat this entire workflow sequentially. Verify one item before starting the next. Stop immediately on an error.

## Commands

Add a local file:

```bash
bash <skill-dir>/scripts/eagle_add.sh \
  --path "/absolute/path/design.png" \
  --name "My Design"
```

Add from an image URL:

```bash
bash <skill-dir>/scripts/eagle_add.sh \
  --url "https://example.com/photo.jpg" \
  --name "Example Photo" \
  --tag "downloaded"
```

Add Base64 data from a text file:

```bash
bash <skill-dir>/scripts/eagle_add.sh \
  --base64-file "/absolute/path/image-base64.txt" \
  --mime "image/png" \
  --name "Encoded Image"
```

Add a bookmark:

```bash
bash <skill-dir>/scripts/eagle_add.sh \
  --bookmark-url "https://www.example.com" \
  --name "Example Site" \
  --tag "bookmark"
```

Append `--execute` only after the dry-run succeeds.

## Reliability Rules

- Require Eagle to be running locally at `http://localhost:41595`.
- Use Eagle's single-item compatibility endpoints:
  - Local path: `/api/item/addFromPath`
  - Image URL or Base64 data URL: `/api/item/addFromURL`
  - Bookmark: `/api/item/addBookmark`
- Require `curl` and `jq`; do not invoke Python.
- Resolve local paths and verify that the source file exists before posting.
- Protect retries by checking for an existing, non-deleted item with the exact same name.
- After every successful POST, read the item back by ID or exact name. Do not report success until verification passes.
- If Eagle accepts a request but the item cannot be verified, stop. The Eagle background process may be unresponsive; restart Eagle and retry instead of sending more requests.
- Use `--allow-duplicate` only when the user explicitly requests another item with the same name.
- Treat `--folder` as one Eagle folder ID. Do not pass a folder name.
- Never expose full Base64 content in a dry-run or response.
- Use `--help` to inspect all options.