Skill: iamngoni/inkdrop (version 1.0.1)

--- name: inkdrop description: Read, create, update, search, and delete notes in Inkdrop via its local HTTP server API. Use when the user asks to take notes, save ideas, manage project notes, read notes, search notes, or interact with Inkdrop in any way. Also use when organizing thoughts, project backlogs, or task lists that should persist in Inkdrop. env: INKDROP_AUTH: required: true description: "Basic auth credentials (user:password) from Inkdrop preferences" INKDROP_URL: required: false description: "Inkdrop local server URL (default: http://localhost:19840)" --- # Inkdrop Notes Interact with Inkdrop's local HTTP server to manage notes, notebooks, and tags. ## Prerequisites 1. [Inkdrop](https://inkdrop.app) desktop app installed and running 2. Local HTTP server enabled in Inkdrop preferences (Preferences → API → Enable Local HTTP Server) 3. Note the port, username, and password from the Inkdrop preferences ## Setup Set environment variables: ```bash export INKDROP_URL="http://localhost:19840" # default port export INKDROP_AUTH="username:password" # from Inkdrop preferences ``` For OpenClaw, store credentials in a secrets file (e.g., workspace `secrets.md`) and source them at runtime. Avoid persisting plaintext credentials in shell profiles. ## Connection ``` Base URL: http://localhost:19840 (or INKDROP_URL env var) Auth: Basic auth via INKDROP_AUTH env var (user:password) ``` Verify connection: ```bash curl -s -u "$INKDROP_AUTH" "${INKDROP_URL:-http://localhost:19840}/" # Returns: {"version":"5.x.x","ok":true} ``` ## API Reference All endpoints use Basic auth. Replace `USER:PASS` with your `$INKDROP_AUTH` value. ### List Notes ```bash curl -s -u $INKDROP_AUTH http://localhost:19840/notes ``` Query params: - `keyword` — search text (same qualifiers as Inkdrop search) - `limit` — max results (default: all) - `skip` — offset for pagination - `sort` — `updatedAt`, `createdAt`, or `title` - `descending` — reverse order (boolean) ### Get Single Document ```bash curl -s -u $INKDROP_AUTH "http://localhost:19840/<docid>" ``` The `docid` is the full `_id` (e.g., `note:abc123`, `book:xyz`). Works for notes, books, tags, files. Optional params: - `rev` — fetch specific revision - `attachments` — include attachment data (boolean, use for file documents) ### Create Note ```bash curl -s -u $INKDROP_AUTH -X POST http://localhost:19840/notes \ -H "Content-Type: application/json" \ -d '{ "doctype": "markdown", "title": "Note Title", "body": "Markdown content here", "bookId": "book:inbox", "status": "none", "tags": [] }' ``` `_id` is auto-generated. `bookId` is required — use `book:inbox` as default or look up notebooks first. ### Update Note POST with `_id` and `_rev` (required to avoid conflicts): ```bash # 1. Get current _rev REV=$(curl -s -u $INKDROP_AUTH "http://localhost:19840/note:abc123" | python3 -c "import sys,json; print(json.load(sys.stdin)['_rev'])") # 2. Update with _rev curl -s -u $INKDROP_AUTH -X POST http://localhost:19840/notes \ -H "Content-Type: application/json" \ -d '{ "_id": "note:abc123", "_rev": "'"$REV"'", "doctype": "markdown", "title": "Updated Title", "body": "Updated content", "bookId": "book:inbox", "status": "none" }' ``` ### Delete Document ```bash curl -s -u $INKDROP_AUTH -X DELETE "http://localhost:19840/<docid>" ``` ### List Notebooks ```bash curl -s -u $INKDROP_AUTH http://localhost:19840/books ``` ### Create Notebook ```bash curl -s -u $INKDROP_AUTH -X POST http://localhost:19840/books \ -H "Content-Type: application/json" \ -d '{"name": "My Notebook"}' ``` ### List Tags ```bash curl -s -u $INKDROP_AUTH http://localhost:19840/tags ``` ### Create Tag ```bash curl -s -u $INKDROP_AUTH -X POST http://localhost:19840/tags \ -H "Content-Type: application/json" \ -d '{"_id": "tag:mytag", "name": "mytag", "color": "blue"}' ``` ### List/Create Files (Attachments) ```bash curl -s -u $INKDROP_AUTH http://localhost:19840/files ``` Create with POST to `/files`. Files are primarily image attachments for notes. ### Changes Feed ```bash curl -s -u $INKDROP_AUTH "http://localhost:19840/_changes?since=0&limit=50&include_docs=true" ``` Params: `since` (sequence number), `limit`, `descending`, `include_docs`, `conflicts`, `attachments`. Returns changes in order they were made. Useful for syncing or watching for updates. ## Helper Script The included `scripts/inkdrop.sh` wraps common operations: ```bash export INKDROP_AUTH="username:password" # List all notes ./scripts/inkdrop.sh notes # Search notes ./scripts/inkdrop.sh search "project ideas" # Get a specific note ./scripts/inkdrop.sh get "note:abc123" # Create a note (title, bookId, body) ./scripts/inkdrop.sh create "My Note" "book:inbox" "Note content here" # List notebooks ./scripts/inkdrop.sh books # List tags ./scripts/inkdrop.sh tags # Delete a document ./scripts/inkdrop.sh delete "note:abc123" ``` ## Note Model | Field | Type | Description | |-------|------|-------------| | `_id` | string | `note:<id>` (auto-generated) | | `_rev` | string | Revision token (required for updates) | | `title` | string | Note title | | `body` | string | Markdown content | | `doctype` | string | Always `"markdown"` | | `bookId` | string | Notebook ID (e.g., `book:inbox`) | | `tags` | string[] | Array of tag IDs | | `status` | string | `none`, `active`, `onHold`, `completed`, `dropped` | | `pinned` | boolean | Pin to top | | `share` | string | `private` or `public` | | `createdAt` | number | Unix timestamp (ms) | | `updatedAt` | number | Unix timestamp (ms) | ## Status Values - `none` — Default - `active` — In progress - `onHold` — Paused - `completed` — Done - `dropped` — Abandoned ## Conventions - Default notebook for quick captures: `book:inbox` - Use existing notebooks when context is clear (match by name via `GET /books`) - Use markdown formatting in note bodies - Always fetch `_rev` before updating to avoid conflicts - Tag IDs use `tag:<name>` format

path: scripts/inkdrop.sh
content: #!/bin/bash
# Inkdrop CLI helper — wraps the local HTTP server API
# Usage: inkdrop.sh <command> [args...]
#
# Environment variables:
#   INKDROP_URL  — Base URL (default: http://localhost:19840)
#   INKDROP_AUTH — user:password for Basic auth (required)

BASE="${INKDROP_URL:-http://localhost:19840}"
AUTH="${INKDROP_AUTH:?Set INKDROP_AUTH=user:password}"

cmd="$1"; shift

case "$cmd" in
  notes)
    curl -s -u "$AUTH" "$BASE/notes?$1"
    ;;
  search)
    curl -s -u "$AUTH" "$BASE/notes?keyword=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$*'))")"
    ;;
  get)
    curl -s -u "$AUTH" "$BASE/$1"
    ;;
  create)
    # args: title bookId [body]
    TITLE="$1"; BOOK="${2:-book:inbox}"; BODY="${3:-}"
    python3 -c "
import json, sys
print(json.dumps({'doctype':'markdown','title':'$TITLE','body':'''$BODY''','bookId':'$BOOK','status':'none','tags':[]}))" | \
    curl -s -u "$AUTH" -X POST "$BASE/notes" -H "Content-Type: application/json" -d @-
    ;;
  update)
    # args: noteId body
    NOTE_ID="$1"; BODY="$2"
    REV=$(curl -s -u "$AUTH" "$BASE/$NOTE_ID" | python3 -c "import sys,json; print(json.load(sys.stdin)['_rev'])")
    NOTE=$(curl -s -u "$AUTH" "$BASE/$NOTE_ID")
    python3 -c "
import json, sys
note = json.loads('''$NOTE''')
note['_rev'] = '$REV'
note['body'] = '''$BODY'''
print(json.dumps(note))" | \
    curl -s -u "$AUTH" -X POST "$BASE/notes" -H "Content-Type: application/json" -d @-
    ;;
  delete)
    curl -s -u "$AUTH" -X DELETE "$BASE/$1"
    ;;
  books)
    curl -s -u "$AUTH" "$BASE/books"
    ;;
  tags)
    curl -s -u "$AUTH" "$BASE/tags"
    ;;
  *)
    echo "Usage: inkdrop.sh <notes|search|get|create|update|delete|books|tags> [args...]"
    echo "Set INKDROP_AUTH=user:password before running."
    exit 1
    ;;
esac


Security scan verdicts — ClawScan: suspicious | static analysis:  | VirusTotal: suspicious | SkillSpector: suspicious (MEDIUM)