Bookshelf

A personal productivity toolkit for managing books, reading plans, progress tracking, reviews, and reading habits — all from the command line with timestamped local logging, tagging, archiving, and weekly review workflows.

Commands

Each command (add, plan, track, etc.) works the same way:

• With arguments: saves the entry with a timestamp to its dedicated .log file and records it in activity history
• Without arguments: displays the 20 most recent entries from that command's log

Data Storage

All data is stored locally in plain-text log files:

~/.local/share/bookshelf/
├── add.log             # Added books and items
├── plan.log            # Reading plans and goals
├── track.log           # Progress tracking entries
├── review.log          # Book reviews and assessments
├── streak.log          # Reading streak records
├── remind.log          # Reminder notes
├── prioritize.log      # Prioritization decisions
├── archive.log         # Archived / finished books
├── tag.log             # Tag and genre categorization
├── timeline.log        # Reading timeline milestones
├── report.log          # Reading reports and summaries
├── weekly-review.log   # Weekly reading review summaries
└── history.log         # Unified activity log with timestamps

Each entry is stored as YYYY-MM-DD HH:MM|\x3Cvalue> for easy parsing and export.

Requirements

• Bash 4.0+ (uses set -euo pipefail)
• Standard UNIX utilities: date, wc, du, grep, head, tail, cat
• No external dependencies or API keys required
• Works offline — all data stays on your machine

When to Use

1. Reading list management — Use add to build your to-read list, prioritize what to pick up next, and archive books once finished or dropped
2. Reading habit tracking — Track daily pages or chapters with track, maintain reading streaks with streak, and review progress in weekly-review
3. Book review journaling — After finishing a book, use review to log your thoughts, ratings, and key takeaways for future reference
4. Annual reading goals — Set yearly targets with plan, track progress with stats, and generate periodic reports with report to stay on pace
5. Genre and tag organization — Use tag to categorize books by genre, topic, or mood, then search to find the right book for any occasion

Examples

Add books and start reading

# Add books to your shelf
bookshelf add "Atomic Habits by James Clear — recommended by Kelly"
bookshelf add "Deep Work by Cal Newport — productivity classic"
bookshelf add "Project Hail Mary by Andy Weir — sci-fi for fun"

# Tag them by genre
bookshelf tag "Atomic Habits: #self-help #habits #productivity"
bookshelf tag "Deep Work: #productivity #focus #career"
bookshelf tag "Project Hail Mary: #sci-fi #fiction #adventure"

# Prioritize what to read next
bookshelf prioritize "Atomic Habits — start this week, short chapters"

Track reading progress

# Track daily reading
bookshelf track "Atomic Habits — finished chapters 1-3, 45 pages"
bookshelf track "Atomic Habits — chapters 4-6, identity-based habits section"

# Record streaks
bookshelf streak "day 7 of reading at least 20 pages daily"
bookshelf streak "day 30 — one month streak! 🎉"

# Set a reminder
bookshelf remind "return library copy of Deep Work by April 20"

# Record a timeline milestone
bookshelf timeline "2024-04-01: started Atomic Habits reading challenge"

Review, report, and archive

# Write a book review
bookshelf review "Atomic Habits — 5/5. Best takeaway: habit stacking. Changed my morning routine."

# Weekly reading review
bookshelf weekly-review "Week 15: finished Atomic Habits (5/5), started Deep Work. Read 180 pages total."

# Generate a monthly report
bookshelf report "April: 2 books finished, 1 in progress. 620 pages read. On track for 24-book goal."

# Set reading plans
bookshelf plan "Q2 goal: finish 6 books — 2 non-fiction, 2 sci-fi, 2 technical"

# Archive finished books
bookshelf archive "Atomic Habits — completed 2024-04-10, review saved"

# Check overall stats
bookshelf stats
bookshelf recent

Search and export

# Search for a book or topic
bookshelf search "productivity"

# Export entire library as JSON
bookshelf export json

# Export as CSV for spreadsheet tracking
bookshelf export csv

# Health check
bookshelf status

Output

All commands print confirmation to stdout. Data is persisted in ~/.local/share/bookshelf/. Use bookshelf stats for an overview, bookshelf search \x3Cterm> to find specific entries, or bookshelf export \x3Cfmt> to extract all data as JSON, CSV, or plain text.

Powered by BytesAgain | bytesagain.com | [email protected]