shelfctl Documentation

Zero-infrastructure document library using GitHub repos and releases as storage.

Getting Started

• Tutorial - Step-by-step guide from installation to common workflows
• Architecture Guide - How shelves work, organization strategies, and scaling
• Interactive Hub - Guide to the interactive TUI menu
• Commands Reference - Complete command documentation with examples
• Troubleshooting - Common issues and solutions

Reference

• Contributing Guide - Development setup and contribution guidelines
• Changelog - Release history and version notes

Quick Links

First Time Setup

1. Authenticate with GitHub
2. Install shelfctl
3. Configure shelfctl
4. Create your first shelf

Common Tasks

• Add a book - shelfctl shelve ~/book.pdf --shelf programming
• Browse your library - shelfctl browse --tag algorithms
• Generate HTML index - shelfctl index for web browsing
• Search books - shelfctl search "neural networks"
• Manage tags - shelfctl tags to list, shelfctl tags rename to bulk rename
• Library status - shelfctl status for sync overview
• Manage cache - shelfctl cache info and shelfctl cache clear
• Edit a book - shelfctl edit-book book-id
• Open a book - shelfctl open book-id
• Migrate existing files - Organize your monolithic repo

Migration Workflows

• From monolithic repo
• Split large shelf
• Import from another shelf

Architecture

shelfctl uses GitHub Releases as a storage backend: - Metadata: Version-controlled catalog.yml files in git repos - Files: PDF/EPUB/etc. stored as Release assets (GitHub's CDN) - Downloads: Individual files on-demand (no need to clone or download entire releases)

See architecture.md for detailed architecture documentation and schemas.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Troubleshooting: Common problems and solutions