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
| 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
- Runs without internet — all data stays on your machine
When to Use
- Reading list management — Use
add to build your to-read list, prioritize what to pick up next, and archive books once finished or dropped
- Reading habit tracking — Track daily pages or chapters with
track, maintain reading streaks with streak, and review progress in weekly-review
- Book review journaling — After finishing a book, use
review to log your thoughts, ratings, and key takeaways for future reference
- Annual reading goals — Set yearly targets with
plan, track progress with stats, and generate periodic reports with report to stay on pace
- 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 | hello@bytesagain.com
1---2name: bookshelf3description: Track reading progress, rate finished books, and manage your library. Use when logging books, reviewing reading stats, or planning reading goals.4---5
6# Bookshelf
7
8A 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.
9
10## Commands
11
12| Command | Description |
13|---------|-------------|
14| `bookshelf add <input>` | Add a book or item to your shelf. Without args, shows recent add entries |
15| `bookshelf plan <input>` | Record a reading plan or goal. Without args, shows recent plans |
16| `bookshelf track <input>` | Track reading progress. Without args, shows recent tracking entries |
17| `bookshelf review <input>` | Log a book review or assessment. Without args, shows recent reviews |
18| `bookshelf streak <input>` | Record a reading streak or consistency milestone. Without args, shows recent streaks |
19| `bookshelf remind <input>` | Set a reading reminder note. Without args, shows recent reminders |
20| `bookshelf prioritize <input>` | Record a prioritization decision. Without args, shows recent priorities |
21| `bookshelf archive <input>` | Archive a finished or dropped book. Without args, shows recent archives |
22| `bookshelf tag <input>` | Tag or categorize a book. Without args, shows recent tag entries |
23| `bookshelf timeline <input>` | Record a reading timeline entry or milestone. Without args, shows recent timeline entries |
24| `bookshelf report <input>` | Generate and log a reading report. Without args, shows recent reports |
25| `bookshelf weekly-review <input>` | Record a weekly reading review summary. Without args, shows recent weekly reviews |
26| `bookshelf stats` | Show summary statistics across all entry types |
27| `bookshelf search <term>` | Search across all log entries for a keyword |
28| `bookshelf recent` | Show the 20 most recent activity entries |
29| `bookshelf status` | Health check — version, data dir, entry count, disk usage, last activity |
30| `bookshelf export <fmt>` | Export all data in json, csv, or txt format |
31| `bookshelf help` | Show all available commands |
32| `bookshelf version` | Print version (v2.0.0) |
33
34Each command (add, plan, track, etc.) works the same way:
35- **With arguments**: saves the entry with a timestamp to its dedicated `.log` file and records it in activity history
36- **Without arguments**: displays the 20 most recent entries from that command's log
37
38## Data Storage
39
40All data is stored locally in plain-text log files:
41
42```
43~/.local/share/bookshelf/
44├── add.log # Added books and items
45├── plan.log # Reading plans and goals
46├── track.log # Progress tracking entries
47├── review.log # Book reviews and assessments
48├── streak.log # Reading streak records
49├── remind.log # Reminder notes
50├── prioritize.log # Prioritization decisions
51├── archive.log # Archived / finished books
52├── tag.log # Tag and genre categorization
53├── timeline.log # Reading timeline milestones
54├── report.log # Reading reports and summaries
55├── weekly-review.log # Weekly reading review summaries
56└── history.log # Unified activity log with timestamps
57```
58
59Each entry is stored as `YYYY-MM-DD HH:MM|<value>` for easy parsing and export.
60
61## Requirements
62
63- **Bash** 4.0+ (uses `set -euo pipefail`)
64- Standard UNIX utilities: `date`, `wc`, `du`, `grep`, `head`, `tail`, `cat`
65- No external dependencies or API keys required
66- Runs without internet — all data stays on your machine
67
68## When to Use
69
701. **Reading list management** — Use `add` to build your to-read list, `prioritize` what to pick up next, and `archive` books once finished or dropped
712. **Reading habit tracking** — Track daily pages or chapters with `track`, maintain reading streaks with `streak`, and review progress in `weekly-review`
723. **Book review journaling** — After finishing a book, use `review` to log your thoughts, ratings, and key takeaways for future reference
734. **Annual reading goals** — Set yearly targets with `plan`, track progress with `stats`, and generate periodic reports with `report` to stay on pace
745. **Genre and tag organization** — Use `tag` to categorize books by genre, topic, or mood, then `search` to find the right book for any occasion
75
76## Examples
77
78### Add books and start reading
79
80```bash
81# Add books to your shelf
82bookshelf add "Atomic Habits by James Clear — recommended by Kelly"
83bookshelf add "Deep Work by Cal Newport — productivity classic"
84bookshelf add "Project Hail Mary by Andy Weir — sci-fi for fun"
85
86# Tag them by genre
87bookshelf tag "Atomic Habits: #self-help #habits #productivity"
88bookshelf tag "Deep Work: #productivity #focus #career"
89bookshelf tag "Project Hail Mary: #sci-fi #fiction #adventure"
90
91# Prioritize what to read next
92bookshelf prioritize "Atomic Habits — start this week, short chapters"
93```
94
95### Track reading progress
96
97```bash
98# Track daily reading
99bookshelf track "Atomic Habits — finished chapters 1-3, 45 pages"
100bookshelf track "Atomic Habits — chapters 4-6, identity-based habits section"
101
102# Record streaks
103bookshelf streak "day 7 of reading at least 20 pages daily"
104bookshelf streak "day 30 — one month streak! 🎉"
105
106# Set a reminder
107bookshelf remind "return library copy of Deep Work by April 20"
108
109# Record a timeline milestone
110bookshelf timeline "2024-04-01: started Atomic Habits reading challenge"
111```
112
113### Review, report, and archive
114
115```bash
116# Write a book review
117bookshelf review "Atomic Habits — 5/5. Best takeaway: habit stacking. Changed my morning routine."
118
119# Weekly reading review
120bookshelf weekly-review "Week 15: finished Atomic Habits (5/5), started Deep Work. Read 180 pages total."
121
122# Generate a monthly report
123bookshelf report "April: 2 books finished, 1 in progress. 620 pages read. On track for 24-book goal."
124
125# Set reading plans
126bookshelf plan "Q2 goal: finish 6 books — 2 non-fiction, 2 sci-fi, 2 technical"
127
128# Archive finished books
129bookshelf archive "Atomic Habits — completed 2024-04-10, review saved"
130
131# Check overall stats
132bookshelf stats
133bookshelf recent
134```
135
136### Search and export
137
138```bash
139# Search for a book or topic
140bookshelf search "productivity"
141
142# Export entire library as JSON
143bookshelf export json
144
145# Export as CSV for spreadsheet tracking
146bookshelf export csv
147
148# Health check
149bookshelf status
150```
151
152## Output
153
154All 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.
155
156---
157
158*Powered by BytesAgain | bytesagain.com | hello@bytesagain.com*
bytesagain