reading-list

name	reading-list
version	1.0
description	Operate the reading-list API to save, manage, tag, search, and export articles.
tools	["Bash","Read","Write","Edit"]

reading-list skill

reading-list is a personal read-it-later app. It fetches article content using Mozilla Readability and stores clean, extracted text in SQLite. Articles can be tagged, filtered by status, searched by full text, and delivered as a daily email digest.

Environment

PORT=3000
DB_PATH=./data/reading-list.db
SESSION_SECRET=<random string>
AUTH_PASSWORD=<bcrypt hash>    # generate: node -e "require('bcryptjs').hash('mypassword',10).then(console.log)"
FETCH_TIMEOUT_MS=10000
# Optional: digest email
DIGEST_SMTP_HOST=smtp.example.com
DIGEST_SMTP_PORT=587
DIGEST_SMTP_USER=[e-mail]
DIGEST_SMTP_PASS=<password>
DIGEST_FROM=[e-mail]
NODE_ENV=production

Starting

pnpm install
pnpm dev          # hot reload
pnpm build && pnpm start
docker compose up  # production

Saving articles

# Save a URL (triggers async fetch + extraction)
curl -X POST http://localhost:3000/api/articles \
  -H 'Content-Type: application/json' \
  -b 'session=...' \
  -d '{"url": "https://blog.golang.org/structured-concurrency"}'

# Poll until status != 'pending'
curl http://localhost:3000/api/articles/:id

Extraction is asynchronous. The article starts with status='pending' and transitions to status='unread' when complete or status='failed' if the fetch fails.

Listing and filtering articles

# All articles
curl http://localhost:3000/api/articles

# Unread only
curl "http://localhost:3000/api/articles?status=unread"

# Filter by tag
curl "http://localhost:3000/api/articles?tag=golang"

# Unread + sorted by newest
curl "http://localhost:3000/api/articles?status=unread&sort=created_at&order=desc"

# Unread, not archived
curl "http://localhost:3000/api/articles?status=unread&archived=0"

# Full-text search
curl "http://localhost:3000/api/articles?q=goroutines+concurrency"

Updating article state

# Mark as read
curl -X PATCH http://localhost:3000/api/articles/:id \
  -H 'Content-Type: application/json' \
  -d '{"status": "read"}'

# Update read progress (0-100)
curl -X PATCH http://localhost:3000/api/articles/:id \
  -H 'Content-Type: application/json' \
  -d '{"read_pct": 65}'

# Star an article
curl -X PATCH http://localhost:3000/api/articles/:id \
  -H 'Content-Type: application/json' \
  -d '{"starred": 1}'

# Archive
curl -X PATCH http://localhost:3000/api/articles/:id \
  -H 'Content-Type: application/json' \
  -d '{"archived": 1}'

# Unarchive
curl -X PATCH http://localhost:3000/api/articles/:id \
  -H 'Content-Type: application/json' \
  -d '{"archived": 0}'

Retrying failed articles

curl -X POST http://localhost:3000/api/articles/:id/refetch

Deleting articles

curl -X DELETE http://localhost:3000/api/articles/:id

Tags

# List tags
curl http://localhost:3000/api/tags

# Create a tag
curl -X POST http://localhost:3000/api/tags \
  -H 'Content-Type: application/json' \
  -d '{"name": "golang", "color": "#00ACD7"}'

# Rename a tag
curl -X PATCH http://localhost:3000/api/tags/:id \
  -H 'Content-Type: application/json' \
  -d '{"name": "go"}'

# Delete a tag (removes from all articles)
curl -X DELETE http://localhost:3000/api/tags/:id

# Add tag to article
curl -X POST http://localhost:3000/api/articles/:id/tags \
  -H 'Content-Type: application/json' \
  -d '{"tagId": "tag_xyz"}'

# Remove tag from article
curl -X DELETE http://localhost:3000/api/articles/:articleId/tags/:tagId

Full-text search

# Search all fields (title, excerpt, content)
curl "http://localhost:3000/api/search?q=goroutines"

# Search returns highlighted snippets
curl "http://localhost:3000/api/search?q=structured+concurrency"

The search endpoint uses SQLite FTS5. Queries support:

• Simple words: concurrency
• Phrases: "structured concurrency" (URL-encode as %22structured+concurrency%22)
• Prefix: gorout*

Import bookmarks

# Import Netscape HTML (browser export)
curl -X POST http://localhost:3000/api/import \
  -F 'file=@bookmarks.html'

# Import JSON array of URLs
curl -X POST http://localhost:3000/api/import \
  -H 'Content-Type: application/json' \
  -d '[
    {"url": "https://example.com/article1", "title": "Article 1"},
    {"url": "https://example.com/article2"}
  ]'

All imported articles are queued for async extraction.

Export

# Export all articles as JSON
curl http://localhost:3000/api/export > reading-list-backup.json

# Export with article content included
curl "http://localhost:3000/api/export?includeContent=1" > full-backup.json

Authentication

reading-list uses a single-password auth model. To get a session:

# Get CSRF token first
CSRF=$(curl -s http://localhost:3000/api/csrf | jq -r '.token')

# Login
curl -X POST http://localhost:3000/api/auth/login \
  -H 'Content-Type: application/json' \
  -H "X-CSRF-Token: $CSRF" \
  -c cookies.txt \
  -d '{"password": "mypassword"}'

# Use session cookie in subsequent requests
curl http://localhost:3000/api/articles -b cookies.txt

Bookmarklet

The bookmarklet JavaScript is available from the settings page at GET /api/settings/bookmarklet. Paste it as the URL of a browser bookmark to enable one-click saving.