Command Reference¶

Complete reference for all shelfctl commands.

Global flags¶

--config string       Config file path (default: ~/.config/shelfctl/config.yml)
--no-color           Disable colored output
--no-interactive     Disable interactive TUI mode

init¶

Bootstrap a shelf repository and initial release.

shelfctl init --repo REPO --name NAME [flags]

Flags¶

--shelf (required for CLI): Target shelf name (interactive prompt if not provided)
--release: Target release tag (default: shelf's default_release)
--id: Book ID (default: slugified title)
--id-sha12: Use first 12 chars of SHA256 as ID
--title: Book title
--author: Author name
--year: Publication year
--tags: Comma-separated tags
--asset-name: Override asset filename
--cache: Cache book locally after upload (default: false in CLI, true in TUI)
--no-push: Update catalog locally only (do not push)
--force: Skip duplicate checks and overwrite existing assets

Examples¶

# Create new private shelf with repo and release (default)
shelfctl init --repo shelf-programming --name programming --create-repo

# Create public shelf
shelfctl init --repo shelf-public --name public --create-repo --private=false

# Initialize existing repo as a shelf
shelfctl init --repo existing-repo --name mybooks

What it does¶

Optionally creates the GitHub repository (with --create-repo)
Creates the 'library' release tag automatically when creating repo
Adds shelf to ~/.config/shelfctl/config.yml
Creates empty catalog.yml in the repo

shelves¶

Validate all configured shelves and show their status.

shelfctl shelves [--fix]

Flags¶

--fix: Automatically create missing catalog.yml files or releases

Output¶

For each shelf: - Shelf name and repository - Repository status (exists on GitHub?) - Catalog.yml status (exists? book count) - Release status (exists?)

Examples¶

# View all shelves with validation
shelfctl shelves

# Validate and auto-repair issues
shelfctl shelves --fix

Example output¶

Shelf: programming  (user/shelf-programming)
  repo:        ok
  catalog.yml: ok (15 books)
  release(library): ok  id=123456789

Shelf: history  (user/shelf-history)
  repo:        ok
  catalog.yml: ok (empty)
  release(library): ok  id=987654321

status¶

Show library sync status and statistics.

shelfctl status [flags]

Flags¶

--shelf: Show status for a specific shelf
-v, --verbose: Show per-book status lines
--json: Output as JSON

Examples¶

# Summary of all shelves
shelfctl status

# Per-book status lines
shelfctl status --verbose

# Filter to one shelf
shelfctl status --shelf programming

# Machine-readable output for scripting
shelfctl status --json

Default Output¶

Shelf: programming (user/shelf-programming)
  12 books, 8 cached, 1 modified

Shelf: history (user/shelf-history)
  5 books, 2 cached

Total: 17 books, 10 cached (142 MiB), 1 modified

Verbose Output¶

Shelf: programming (user/shelf-programming)
  ✓ cached    design-patterns.pdf
  ✓ cached    sicp.pdf
  ✗ modified  clean-code.pdf
  · remote    golang-spec.pdf

Total: 4 books, 3 cached (89 MiB), 1 modified

Status Icons¶

Icon	Meaning
`✓`	Cached locally, matches remote
`✗`	Cached locally, has local modifications
`·`	Remote only, not cached

search¶

Search books by title, author, or tags across all shelves.

shelfctl search <query> [flags]

Flags¶

--shelf: Search within a specific shelf
--tag: Filter results by tag
--format: Filter by format (pdf, epub, ...)
--json: Output as JSON

Examples¶

# Full-text search across title, author, and tags
shelfctl search "neural networks"

# Search within a specific shelf
shelfctl search golang --shelf programming

# Combine search with tag filter
shelfctl search "smith" --tag research

# Filter by format
shelfctl search --tag fiction --format epub

# Machine-readable output
shelfctl search "algorithms" --json

Example Output¶

── programming  (3 matches)
  design-patterns       Design Patterns [oop,architecture] ✓
  sicp                  Structure and Interpretation [lisp,cs]
  clean-code            Clean Code [craftsmanship] ✓

3 result(s)

The ✓ mark indicates the book is cached locally.

tags¶

List and manage tags across your library.

tags list¶

List all tags with book counts (default when running shelfctl tags with no subcommand).

shelfctl tags [list] [flags]

Flags¶

--shelf: List tags for a specific shelf
--json: Output as JSON

Example Output¶

  programming              (12)
  algorithms               (8)
  machine-learning         (5)
  fiction                   (3)
  history                   (2)

5 tags across 3 shelves

tags rename¶

Rename all occurrences of a tag across shelves.

shelfctl tags rename <old> <new> [flags]

Flags¶

--shelf: Rename only within a specific shelf
--dry-run: Show what would be renamed without saving

Examples¶

# Rename a tag across all shelves
shelfctl tags rename "prog" "programming"

# Preview changes first
shelfctl tags rename ml machine-learning --dry-run

# Rename within one shelf only
shelfctl tags rename "cs" "computer-science" --shelf research

shelve¶

Add a book to your library.

shelfctl shelve [file|url|github:owner/repo@ref:path] [flags]

Interactive Mode (no arguments)¶

When run in a terminal with no arguments, shelve launches a fully guided workflow:

Select shelf - Choose from configured shelves
Pick file - Browse filesystem (starts in ~/Downloads, shows .pdf/.epub/.mobi/.djvu)
Enter metadata - Fill form with title, author, tags, ID
Upload - Automatic upload to GitHub and catalog update

# Fully interactive
shelfctl shelve

Arguments¶

Source can be: - Local file: ~/Downloads/book.pdf - HTTP URL: https://example.com/book.pdf - GitHub repo: github:user/repo@main:path/to/book.pdf - None: launches file picker (interactive mode)

Flags¶

--shelf: Target shelf name (interactive picker if omitted)
--title: Book title (prompts if omitted)
--author: Author name
--year: Publication year
--tags: Comma-separated tags (e.g., cs,algorithms)
--id: Book ID (default: prompt or slugified title)
--id-sha12: Use first 12 chars of SHA256 as ID
--release: Target release tag (default: shelf's default)
--asset-name: Override asset filename
--cache: Cache book locally after upload (default: false in CLI, checkbox in TUI defaults to true)
--no-push: Update catalog locally without pushing
--force: Skip duplicate checks and overwrite existing assets
--create-shelf: Auto-create the shelf if it doesn't exist (creates private repo shelf-<name> with release)

Examples¶

# Fully interactive (no arguments)
shelfctl shelve

# Interactive form with file provided
shelfctl shelve ~/Downloads/sicp.pdf

# Non-interactive with all metadata
shelfctl shelve ~/Downloads/sicp.pdf \
  --shelf programming \
  --title "Structure and Interpretation of Computer Programs" \
  --author "Abelson & Sussman" \
  --tags lisp,cs,textbook

# Add from URL
shelfctl shelve https://example.com/paper.pdf \
  --shelf research \
  --title "Important Paper" \
  --year 2024

# Add from GitHub repo
shelfctl shelve github:user/books@main:pdfs/algo.pdf \
  --shelf cs \
  --title "Algorithm Design"

# Use SHA-based ID for uniqueness
shelfctl shelve book.pdf --shelf fiction --id-sha12 --title "Novel"

# Cache locally after upload (ready to open immediately)
shelfctl shelve book.pdf --shelf programming --title "..." --cache

# Force overwrite existing asset
shelfctl shelve ~/Downloads/sicp-v2.pdf \
  --shelf programming \
  --id sicp \
  --title "SICP (Updated Edition)" \
  --force

What it does¶

Interactive mode: Launches shelf/file pickers and metadata form
Downloads/reads the source file
Computes SHA256 checksum and size
Extracts PDF cover thumbnail automatically (if pdftoppm installed)
Collects metadata (interactively or from flags)
Checks for duplicates (SHA256 and asset name, skipped with --force)
Uploads file as GitHub release asset
Updates catalog.yml with metadata
Commits and pushes catalog changes

Note: The --force flag bypasses duplicate checks and will overwrite existing assets with the same name.

browse¶

Browse your library (interactive TUI or text output).

shelfctl browse [--shelf NAME] [--tag TAG] [--format FORMAT]

Interactive Mode (TUI)¶

When run in a terminal, browse shows an interactive browser with: - Keyboard navigation (↑/↓ or j/k) - Live filtering (press / to search) - Visual display with tags and cache status - Color-coded indicators (green ✓ = cached) - Interactive actions: - enter - Show detailed book information - o - Open book (downloads if needed, opens with system viewer) - space - Toggle selection (checkboxes appear for multi-select) - g - Download selected books to cache (or current if none selected) - x - Remove selected books from cache (or current if none selected) - s - Sync modified books to GitHub (uploads annotations/highlights) - e - Edit book metadata - c - Clear all selections - tab - Toggle details panel - q - Quit browser

Multi-select workflow: - Press space to check books for batch operations - Press g to download all selected books (useful for pre-caching for offline) - Press x to remove selected books from cache (frees disk space without deleting from shelf) - Press s to sync modified books to GitHub (replaces release assets with annotated versions) - Books stay in catalog/release, only local cache affected by download/uncache

Downloads happen in background without exiting TUI - progress bar shows at bottom of screen.

Use --no-interactive or pipe output to get text mode.

Flags¶

--shelf: Filter by shelf name
--tag: Filter by tag
--format: Filter by format (pdf, epub, etc.)
--search: Full-text search across title, author, tags

Examples¶

# List all books
shelfctl browse

# List books in specific shelf
shelfctl browse --shelf programming

# Filter by tag
shelfctl browse --tag algorithms

# Combine filters
shelfctl browse --shelf programming --tag lisp

Output¶

programming/sicp
  Structure and Interpretation of Computer Programs
  Abelson & Sussman
  tags: lisp, cs, textbook
  format: pdf, 6.2 MB

programming/taocp-vol1
  The Art of Computer Programming, Vol 1
  Donald Knuth
  tags: algorithms, cs
  format: pdf, 15.8 MB

cache¶

Manage local book cache without affecting shelf metadata or release assets.

shelfctl cache [command]

Subcommands¶

cache clear¶

Remove books from local cache. Books remain in catalog and release - only local copies deleted.

Protection for modified files: By default, books with local changes (annotations/highlights) are protected and won't be deleted. Use --force to override.

shelfctl cache clear [book-id...] [flags]

Flags: - --shelf: Clear cache for all books on this shelf - --all: Clear entire cache directory - --force: Delete modified files (with annotations/highlights)

Examples:

# Interactive picker (multi-select with spacebar)
shelfctl cache clear

# Remove specific books (skips modified files)
shelfctl cache clear sicp taocp-vol1

# Force delete including modified files
shelfctl cache clear sicp --force

# Clear all books from a shelf (protects modified)
shelfctl cache clear --shelf programming

# Clear shelf including modified files
shelfctl cache clear --shelf programming --force

# Nuke entire cache (requires "CLEAR ALL CACHE" confirmation)
shelfctl cache clear --all

What it does: 1. Checks for modified files (annotations/highlights) 2. Skips modified files by default, warns with sync suggestion 3. Shows confirmation prompt for bulk operations 4. Removes cached files from ~/.cache/shelfctl/ 5. Books remain in catalog.yml and release assets 6. Books will re-download when opened or browsed 7. Useful for reclaiming disk space without affecting library

Protection behavior:

# Without --force (safe)
$ shelfctl cache clear sicp
⚠ sicp: modified (use --force to delete)
  Tip: Run 'shelfctl sync sicp' to upload changes first

# With --force (destructive)
$ shelfctl cache clear sicp --force
⚠ This includes modified files with annotations
Type 'CLEAR CACHE' to confirm: _

cache info¶

Show cache statistics and disk usage.

shelfctl cache info [--shelf NAME]

Flags: - --shelf: Show stats for specific shelf only

Examples:

# Overall cache statistics
shelfctl cache info

# Stats for specific shelf
shelfctl cache info --shelf programming

Output:

Cache Statistics
  total_books: 50
  cached_books: 32
  modified: 3 (annotations/highlights)
  cache_size: 2.3 GB
  cache_dir: /Users/you/.cache/shelfctl

⚠ 18 books not cached
ℹ 3 books have local changes
  Run 'shelfctl sync --all' to upload changes to GitHub

sync¶

Upload locally modified books back to GitHub. When you annotate or highlight cached PDFs, those changes only exist locally. This command detects modifications and re-uploads to keep GitHub in sync with your working copies.

shelfctl sync [book-id...] [flags]

TUI Mode¶

Press s in the browse view to sync books directly from the TUI: - Single book: Navigate to a modified book and press s to sync it - Batch sync: Press space to select multiple modified books, then press s to sync all selected - Shows progress messages during sync operation - Displays "[N/M]" counter when syncing multiple books - Returns to browse view after completion

Flags¶

--shelf: Limit to specific shelf
--all: Sync all modified cached books

Examples¶

# Sync specific book
shelfctl sync sicp

# Sync multiple books
shelfctl sync book-1 book-2 book-3

# Sync all modified books (with progress indicators)
shelfctl sync --all

# Sync all modified books on a shelf
shelfctl sync --all --shelf programming

How it works¶

Scans for modified books (compares cached file SHA256 with catalog)
Shows progress counter: "[2/5] Syncing book-id"
For each modified book:
Deletes old Release asset
Uploads modified file with progress bar
Updates catalog with new SHA256 and size
No versioning - GitHub always has your latest annotated copy
Single catalog commit per shelf with all updates

When to use¶

After annotating/highlighting PDFs in your PDF reader
Before clearing cache (to preserve annotations on GitHub)
To share annotated versions with other machines
Shown in cache info output: "3 books have local changes"

Notes¶

Only processes cached books (skips uncached)
Replaces Release asset (no version history for annotations)
Safe: catalog SHA256 always matches Release asset after sync
Commits once per shelf: "sync: update 3 books with local changes"
Silent for unmodified books when using --all

verify¶

Detect mismatches between catalog entries and release assets, and optionally auto-fix them.

shelfctl verify [flags]

Flags¶

--shelf: Verify a specific shelf only
--fix: Automatically clean up issues

What it checks¶

Orphaned catalog entries — book listed in catalog.yml but its asset is missing from the GitHub Release
Orphaned release assets — file exists in the Release but is not referenced by any catalog entry

What `--fix` does¶

Removes orphaned catalog entries from catalog.yml and clears their local cache
Deletes orphaned assets from the GitHub Release
Commits the cleaned-up catalog with a summary message
Updates the shelf README with the new book count

Examples¶

# Check all shelves for issues
shelfctl verify

# Check a specific shelf
shelfctl verify --shelf programming

# Auto-fix all issues
shelfctl verify --fix

Example Output¶

Verifying shelf: programming
  Owner/Repo: user/shelf-programming
  Release: library
  Catalog: 15 entries
  Release: 14 assets

Issues found:
  ✗ Orphaned catalog entry: old-book
    - Asset "old-book.pdf" missing from release
    - Fix: Remove from catalog

delete-book¶

Remove a book from your library.

shelfctl delete-book [id] [flags]

Interactive Mode (no arguments)¶

When run in a terminal with no arguments, delete-book shows an interactive book picker:

# Interactive picker
shelfctl delete-book

Flags¶

--shelf: Specify shelf if book ID is ambiguous
--yes: Skip confirmation prompt

Examples¶

# Interactive mode - shows picker
shelfctl delete-book

# Direct deletion
shelfctl delete-book sicp --shelf programming

# Skip confirmation
shelfctl delete-book sicp --yes

What it does¶

Finds the book in your library
Shows book details and warning
Requires confirmation (type book ID to confirm)
Deletes the GitHub release asset (PDF/EPUB file)
Removes entry from catalog.yml
Clears from local cache if present
Commits updated catalog

Warning: This is a destructive operation and cannot be easily undone.

edit-book¶

Edit metadata for a book in your library.

shelfctl edit-book [id] [flags]

Interactive Mode (no arguments)¶

When run in a terminal with no arguments, edit-book shows an interactive book picker followed by a form:

# Interactive mode - shows picker then form
shelfctl edit-book

The form pre-populates with current metadata values for easy editing.

Flags¶

--shelf: Specify shelf if book ID is ambiguous
--title: New title
--author: New author
--year: Publication year
--add-tag: Add tags (comma-separated, can be used multiple times)
--rm-tag: Remove tags (comma-separated, can be used multiple times)

Examples¶

# Interactive mode - form with current values
shelfctl edit-book design-patterns

# Update title only
shelfctl edit-book design-patterns --title "Design Patterns (Gang of Four)"

# Update author and year
shelfctl edit-book gopl --author "Donovan & Kernighan" --year 2015

# Add tags incrementally
shelfctl edit-book sicp --add-tag favorites --add-tag classics

# Remove a tag
shelfctl edit-book sicp --rm-tag draft

# Combine multiple changes
shelfctl edit-book gopl --title "The Go Programming Language" --add-tag reference

What it does¶

Finds the book in your library
Shows interactive form (TUI) or applies flag changes (CLI)
Updates catalog.yml with new metadata
Commits changes to GitHub
Asset file remains unchanged (only metadata updates)

What you can edit¶

Title
Author
Year
Tags (add/remove incrementally or replace all)

What you cannot edit¶

ID (used for commands and asset naming)
Format (tied to the file)
Checksum (tied to file content)
Asset filename (tied to the file)

Note: This only updates catalog metadata. The actual PDF/EPUB file is not modified or re-uploaded.

delete-shelf¶

Remove a shelf from your configuration.

shelfctl delete-shelf [name] [flags]

Interactive Mode (no arguments)¶

When run with no arguments, shows an interactive shelf picker:

# Interactive picker
shelfctl delete-shelf

Flags¶

--delete-repo: Also delete the GitHub repository (DESTRUCTIVE)
--yes: Skip confirmation prompt

Examples¶

# Remove from config only (keeps repo)
shelfctl delete-shelf old-books

# Remove AND delete the GitHub repo permanently
shelfctl delete-shelf old-books --delete-repo --yes

What it does¶

By default (without --delete-repo): 1. Removes shelf from your config file 2. Keeps the GitHub repository and all books 3. You can re-add the shelf later with shelfctl init

With --delete-repo: 1. Removes shelf from your config file 2. Permanently deletes the GitHub repository 3. Deletes all books (release assets) 4. Deletes all catalog history 5. This cannot be undone

Interactive Prompts¶

When run interactively, you'll see: 1. Shelf picker (if no name provided) 2. Repository choice: - Keep it (default) - Remove from config only - Delete permanently - Delete repository and all books 3. Confirmation (type shelf name to confirm)

info¶

Show detailed metadata and cache status for a book.

shelfctl info <id>

Arguments¶

id: Book ID (searches across all shelves)

Flags¶

--shelf: Specify shelf if book ID exists in multiple shelves

Examples¶

# Find book across all shelves
shelfctl info sicp

# Specify shelf if ID is ambiguous
shelfctl info paper-2024 --shelf research

Output¶

ID:        sicp
Title:     Structure and Interpretation of Computer Programs
Author:    Abelson & Sussman
Year:      1996
Tags:      lisp, cs, textbook
Format:    pdf
Size:      6.2 MB
SHA256:    a1b2c3d4...
Source:    github_release
  Owner:   your-username
  Repo:    shelf-programming
  Release: library
  Asset:   sicp.pdf
Cache:     cached (/Users/you/.local/share/shelfctl/cache/sicp.pdf)
Added:     2024-01-15T10:30:00Z

open¶

Open a book (auto-downloads if needed).

shelfctl open <id> [flags]

Arguments¶

id: Book ID (searches across all shelves)

Flags¶

--shelf: Specify shelf if book ID exists in multiple shelves
--app: Application to open the file with (overrides system default)

Examples¶

# Open with system default viewer
shelfctl open sicp

# Specify shelf if ID is ambiguous
shelfctl open paper-2024 --shelf research

# Open with specific application
shelfctl open sicp --app "Preview"

# Open with command-line viewer
shelfctl open doc --app "less"

What it does¶

Downloads book if not in cache
Verifies checksum
Opens file with specified application or system default
macOS: uses open (or specified app)
Linux: uses xdg-open (or specified app)
Windows: uses start (or specified app)

move¶

Move a book between releases or shelves.

Interactive mode: Run shelfctl move with no arguments to use the guided workflow: - Pick which book to move - Choose between different shelf or different release - Select destination shelf (if moving to different shelf) - Optionally specify release tag - Confirm before executing

Command line mode:

shelfctl move <id> [flags]

Flags¶

--shelf: Source shelf (if book ID is ambiguous)
--to-shelf: Target shelf name
--to-release: Target release tag
--keep-old: Keep the original asset (don't delete after copying)
--dry-run: Show what would happen without making changes
--create-shelf: Auto-create the destination shelf if it doesn't exist

Examples¶

# Interactive mode (pick book, choose destination)
shelfctl move

# Move to different release in same shelf
shelfctl move book-id --to-release 2024

# Move to different shelf
shelfctl move book-id --to-shelf history

# Move to different shelf and release
shelfctl move book-id --to-shelf history --to-release archive

# Keep original asset when moving
shelfctl move book-id --to-shelf backup --keep-old

# Preview move operation without executing
shelfctl move book-id --to-shelf history --dry-run

# Specify source shelf if ID is ambiguous
shelfctl move paper-2024 --shelf research --to-shelf archive

What it does¶

Downloads book from source
Uploads to target release
Updates target catalog
Removes from source catalog
Optionally deletes source asset (use --keep-old to preserve)
Commits both catalog changes

Note: Use --dry-run to preview changes before executing. Use --keep-old to copy rather than move (keeps the original asset).

split¶

Interactive wizard to split a shelf into multiple shelves.

shelfctl split

Interactive workflow¶

Select source shelf
Define target shelves
Map books to target shelves (by tag, title pattern, etc.)
Review migration plan
Execute split

Use this when a shelf grows too large or topics diverge.

Note: If a target shelf doesn't exist, shelfctl will prompt to create it (or auto-create with --create-shelf).

migrate one¶

Migrate a single file from an old repository.

shelfctl migrate one <source> <path> --shelf NAME [flags]

Arguments¶

source: Source repo in format owner/repo@ref
path: Path to file in source repo

Flags¶

--shelf (required): Target shelf name
--title: Book title (prompts if omitted)
--author, --year, --tags: Metadata
--create-shelf: Auto-create the target shelf if it doesn't exist

Example¶

shelfctl migrate one user/old-books@main books/sicp.pdf \
  --shelf programming \
  --title "SICP" \
  --tags lisp,cs

migrate batch¶

Migrate multiple files from a queue.

shelfctl migrate batch <queue-file> [flags]

Arguments¶

queue-file: File with one migration per line (see format below)

Flags¶

--n: Process only first N entries
--continue: Skip entries already in ledger
--ledger: Ledger file path (default: .shelfctl-ledger.txt)

Queue file format¶

owner/repo@ref:path/to/file.pdf shelf=programming title="..." tags=cs,algo
owner/repo@ref:another.pdf shelf=history title="..."

Example¶

# Generate queue from old repo
shelfctl migrate scan --source user/old-books > queue.txt

# Edit queue.txt to add metadata

# Migrate in batches
shelfctl migrate batch queue.txt --n 10 --continue

# Continue from where you left off
shelfctl migrate batch queue.txt --continue

Ledger¶

The ledger file tracks completed migrations to support resumption. Format:

[OK] owner/repo@ref:path/to/file.pdf shelf=programming id=book-id
[X] owner/repo@ref:failed.pdf error: file not found

migrate scan¶

List all files in a source repository.

shelfctl migrate scan --source owner/repo[@ref]

Flags¶

--source (required): Source repo in format owner/repo[@ref] (default ref: main)

Example¶

# Scan repo and generate queue
shelfctl migrate scan --source user/old-books > queue.txt

# Scan specific ref
shelfctl migrate scan --source user/old-books@archive > archive-queue.txt

Output format¶

One file per line:

user/old-books@main:books/programming/sicp.pdf
user/old-books@main:books/history/rome.pdf
user/old-books@main:papers/algo.pdf

index¶

Generate a local HTML index for browsing cached books in a web browser.

shelfctl index

What it does¶

Scans all configured shelves
Collects books that are in your local cache
Generates index.html in your cache directory (~/.local/share/shelfctl/cache/index.html)
Includes cover images if available (catalog covers or auto-extracted thumbnails)

Features¶

Visual book grid with covers and metadata
Real-time search/filter by title, author, or tags (no server needed)
Clickable tag filters with word cloud interface (multi-tag AND logic)
Sort options - Recently Added, Title (A-Z), Author (A-Z), Year (Newest/Oldest)
Organized by shelf sections
Click books to open with system viewer (file:// links)
Responsive layout for mobile/desktop
Dark theme matching shelfctl aesthetic

Flags¶

Flag	Description
`--open`	Open the generated index in the default browser immediately after generation

Usage¶

# Generate index
shelfctl index

# Generate and open in browser
shelfctl index --open

# Open manually (macOS)
open ~/.local/share/shelfctl/cache/index.html

# Open manually (Linux)
xdg-open ~/.local/share/shelfctl/cache/index.html

Notes¶

Shows only cached books (download books first to include them)
Works without running shelfctl - just open in any browser
Updates automatically each time you run shelfctl index
Useful for offline browsing or sharing your library locally

Browser Compatibility¶

The index uses file:// protocol links to open books directly from your filesystem. Browser support varies due to security restrictions:

Safari (macOS): ✅ Generally works - allows file:// navigation from file:// pages
Firefox: ⚠️ May work by default, or may require security.fileuri.strict_origin_policy=false in about:config
Chrome/Edge: ❌ Most restrictive - blocks file:// navigation for security reasons

If clicking doesn't open books: 1. Use Safari for best compatibility 2. Right-click book card → "Copy Link Address" → open in terminal: open <paste-path> 3. Use the TUI browser instead: shelfctl browse (always works, no restrictions)

import¶

Import books from another shelfctl shelf.

shelfctl import --from owner/repo --shelf TARGET [flags]

Flags¶

--from (required): Source shelf as owner/repo
--shelf (required): Destination shelf name
--release: Destination release tag (default: shelf's default_release)
--dry-run: Show what would be imported without doing it
-n: Limit number of books to import
--no-push: Update catalog locally only
--create-shelf: Auto-create the destination shelf if it doesn't exist

Examples¶

# Import all books from another user's shelf
shelfctl import --from other-user/shelf-programming --shelf programming

# Import to specific release
shelfctl import --from other-user/shelf-research --shelf papers --release archive

# Preview import without executing
shelfctl import --from other-user/shelf-books --shelf library --dry-run

# Limit import batch size
shelfctl import --from other-user/shelf-prog --shelf cs -n 20

What it does¶

Reads source catalog from owner/repo
For each book:
Downloads from source
Uploads to target release
Adds to target catalog
Commits target catalog

Note: Source catalog is not modified. This is a copy operation.

completion¶

Generate shell autocompletion scripts for shelfctl.

shelfctl completion [bash|zsh|fish|powershell]

Supported Shells¶

bash - Bourne Again Shell
zsh - Z Shell
fish - Friendly Interactive Shell
powershell - PowerShell

Setup Instructions¶

Bash¶

# Load completions in current session
source <(shelfctl completion bash)

# Install permanently (Linux)
shelfctl completion bash > /etc/bash_completion.d/shelfctl

# Install permanently (macOS with Homebrew)
shelfctl completion bash > $(brew --prefix)/etc/bash_completion.d/shelfctl

Requires bash-completion package to be installed.

Zsh¶

# Load completions in current session
source <(shelfctl completion zsh)

# Install permanently
shelfctl completion zsh > "${fpath[1]}/_shelfctl"

Then restart your shell or run compinit.

Fish¶

# Install permanently
shelfctl completion fish > ~/.config/fish/completions/shelfctl.fish

PowerShell¶

# Add to PowerShell profile
shelfctl completion powershell | Out-String | Invoke-Expression

# Save to profile permanently
shelfctl completion powershell >> $PROFILE

What it provides¶

Command name completion (shelfctl bro<tab> → shelfctl browse)
Flag completion (shelfctl shelve --sh<tab> → shelfctl shelve --shelf)
Shelf name completion (completes configured shelf names)
Book ID completion where applicable

Examples¶

# Generate bash completion script
shelfctl completion bash

# Generate zsh completion script
shelfctl completion zsh > _shelfctl

Command Reference¶

Global flags¶

init¶

Flags¶

Examples¶

What it does¶

shelves¶

Flags¶

Output¶

Examples¶

Example output¶

status¶

Flags¶

Examples¶

Default Output¶

Verbose Output¶

Status Icons¶

search¶

Flags¶

Examples¶

Example Output¶

tags¶

tags list¶

Flags¶

Example Output¶

tags rename¶

Flags¶

Examples¶

shelve¶

Interactive Mode (no arguments)¶

Arguments¶

Flags¶

Examples¶

What it does¶

browse¶

Interactive Mode (TUI)¶

Flags¶

Examples¶

Output¶

cache¶

Subcommands¶

cache clear¶

cache info¶

sync¶

TUI Mode¶

Flags¶

Examples¶

How it works¶

When to use¶

Notes¶

verify¶

Flags¶

What it checks¶

What --fix does¶

Examples¶

Example Output¶

delete-book¶

Interactive Mode (no arguments)¶

Flags¶

Examples¶

What it does¶

edit-book¶

Interactive Mode (no arguments)¶

Flags¶

Examples¶

What it does¶

What you can edit¶

What you cannot edit¶

delete-shelf¶

Interactive Mode (no arguments)¶

Flags¶

Examples¶

What it does¶

Interactive Prompts¶

info¶

Arguments¶

Flags¶

Examples¶

Output¶

open¶

What `--fix` does¶