Bookshelf

Track reading progress, rate finished books, and manage your library. Use when logging books, reviewing reading stats, or planning reading goals.

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

Command	Description
bookshelf add <input>	Add a book or item to your shelf. Without args, shows recent add entries
bookshelf plan <input>	Record a reading plan or goal. Without args, shows recent plans
bookshelf track <input>	Track reading progress. Without args, shows recent tracking entries
bookshelf review <input>	Log a book review or assessment. Without args, shows recent reviews
bookshelf streak <input>	Record a reading streak or consistency milestone. Without args, shows recent streaks
bookshelf remind <input>	Set a reading reminder note. Without args, shows recent reminders
bookshelf prioritize <input>	Record a prioritization decision. Without args, shows recent priorities
bookshelf archive <input>	Archive a finished or dropped book. Without args, shows recent archives
bookshelf tag <input>	Tag or categorize a book. Without args, shows recent tag entries
bookshelf timeline <input>	Record a reading timeline entry or milestone. Without args, shows recent timeline entries
bookshelf report <input>	Generate and log a reading report. Without args, shows recent reports
bookshelf weekly-review <input>	Record a weekly reading review summary. Without args, shows recent weekly reviews
bookshelf stats	Show summary statistics across all entry types
bookshelf search <term>	Search across all log entries for a keyword
bookshelf recent	Show the 20 most recent activity entries
bookshelf status	Health check — version, data dir, entry count, disk usage, last activity
bookshelf export <fmt>	Export all data in json, csv, or txt format
bookshelf help	Show all available commands
bookshelf version	Print version (v2.0.0)

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|<value> 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 <term> to find specific entries, or bookshelf export <fmt> to extract all data as JSON, CSV, or plain text.

---

Powered by BytesAgain | bytesagain.com | [e-mail]