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.

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:

Checks for modified files (annotations/highlights)
Skips modified files by default, warns with sync suggestion
Shows confirmation prompt for bulk operations
Removes cached files from ~/.cache/shelfctl/
Books remain in catalog.yml and release assets
Books will re-download when opened or browsed
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

Hub menu (recommended): When modified books are detected, a Sync Modified item appears in the Cache section of the hub menu. Selecting it opens a dedicated view that:

Scans all shelves for modified books (comparing cached SHA256 against catalog)
Shows the full list for confirmation before proceeding
Uploads each book sequentially with live ✓/✗ status per book
Returns to the hub with a summary on completion

Browse view: Press s to sync directly from browse:

Single book: Navigate to a modified book and press s
Batch sync: Press space to select multiple books, then s

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):

Removes shelf from your config file
Keeps the GitHub repository and all books
You can re-add the shelf later with shelfctl init

With --delete-repo:

Removes shelf from your config file
Permanently deletes the GitHub repository
Deletes all books (release assets)
Deletes all catalog history
This cannot be undone

Interactive Prompts

When run interactively, you'll see:

Shelf picker (if no name provided)
Repository choice:
- Keep it (default) - Remove from config only
- Delete permanently - Delete repository and all books
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:

Use Safari for best compatibility
Right-click book card → "Copy Link Address" → open in terminal: open <paste-path>
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

Configuration

Config file location

Default: ~/.config/shelfctl/config.yml

Override with --config <path>.

`sync`

Field	Type	Default	Description
`sync.auto_sync`	bool	`false`	When `true`, automatically upload modified books from the hub without confirmation.
`sync.debounce_minutes`	int	`5`	Skip files modified within this many minutes (avoids uploading files still being written).

Example:

sync:
  auto_sync: true
  debounce_minutes: 10

FilesExpand file tree

commands.md

Latest commit

History

commands.md

File metadata and controls

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

What `--fix` does

`sync`