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 <skill-dir>/scripts/eagle_add.sh \
  --path "/absolute/path/design.png" \
  --name "My Design"

Add from an image URL:

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 <skill-dir>/scripts/eagle_add.sh \
  --base64-file "/absolute/path/image-base64.txt" \
  --mime "image/png" \
  --name "Encoded Image"

Add a bookmark:

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.