zen-prompt 0.2.0

Aesthetic inspiration for your shell

Zen Prompt

Aesthetic inspiration for your shell.

Features

• Shell Inspiration First: Instantly generate aesthetic quote prompts with zen-prompt random, using quotes collected from Goodreads and optional photo layouts for a more atmospheric terminal experience.
• Resumable Crawling: Collect more quotes from Goodreads over time and resume from the last processed page for each tag.
• Quote Statistics: Explore the collection later with database statistics and exports once your cache grows.

Tech Stack

• Python 3.13+
• uv: Dependency management and project isolation.
• Scrapy: High-level crawling and scraping.
• SQLite: Local persistence and state management.
• Typer: CLI command parsing.
• textual-image: Terminal image rendering for photo-backed quote output.
• Pydantic: Data validation.

Setup

Install the lightweight runtime by default:

pip install zen-prompt

This installs the zen-prompt command-line tool with the runtime features needed for:

• random
• sync
• history
• profile
• search
• get
• stat
• distill
• export

If you also want crawling support, install the full extra:

pip install "zen-prompt[all]"

The all extra adds the crawler stack used by zen-prompt crawl.

For local development installs with pipx, use the helper script:

# Lightweight install
scripts/install-local

# Full install with crawl support
scripts/install-local full

Usage

After installation, you can use the zen-prompt command directly.

Random Inspiration

Start with the main experience: generate quotes collected from Goodreads directly in your shell.

Tip: add zen-prompt random to your shell startup file so each new terminal session opens with a fresh quote.

# zsh
echo 'zen-prompt random' >> ~/.zshrc

# bash
echo 'zen-prompt random' >> ~/.bashrc

# Get a random quote with the default monochrome photo
zen-prompt random

# Disable the default photo
zen-prompt random --no-photo

# Pick only shorter quotes
zen-prompt random --quote-max-words 20 --quote-max-chars 140

# Pick a random hero photo from a topic
zen-prompt random --photo topic@monochrome

# Control image size in the terminal
zen-prompt random --photo topic@monochrome --photo-max-height 10 --photo-max-width 80

# Render photo and quote side by side
zen-prompt random --photo topic@monochrome --photo-layout table

# Wrap long quotes to a fixed width
zen-prompt random --quote-width 60

# Reuse a fixed image for every quote
zen-prompt random --photo file@./cover.png

Below is an example of a quote with a custom photo

Crawling Later

Build data in stages. The default tags are inspirational,motivational,buddhism.

# 1. Crawl raw quotes
zen-prompt crawl --tags inspirational,life

# 2. Distill raw quotes into a curated database
zen-prompt distill

# 3. Export runtime assets used by random/search/get/stat
zen-prompt export --output-dir ./docs --small-limit 500

# Crawl from a specific Goodreads URL (author, book, etc.)
zen-prompt crawl --url https://www.goodreads.com/author/zen-prompt/123.Author_Name

# Configurable download delay (default 1s)
zen-prompt crawl --download-delay 2.0

By default:

• crawl writes docs/data/sqlite/quotes-raw.db
• distill writes docs/data/sqlite/quotes-distilled.db
• export publishes runtime assets including docs/data/sqlite/quotes.db

Package builds only bundle the small runtime database. To fetch the large runtime database after install, run zen-prompt sync.

Quote Statistics Later

Once you have a local cache, inspect the quote database with summary statistics.

# Print statistics in the terminal
zen-prompt stat

# Save statistics as Markdown
zen-prompt stat --output stats.md

Exporting

Export your collection as optimized web and CLI assets.

# Export optimized SQLite and JSON files to ./docs
zen-prompt export --output-dir ./docs --small-limit 500

This command creates:

• docs/data/sqlite/quotes.db: Complete optimized database with FTS5 search.
• docs/data/sqlite/quotes-small.db: Small subset (tag: buddhism) for instant availability.
• docs/data/json/quotes.json & docs/data/json/quotes-small.json: JSON versions of the databases.
• docs/data/csv/quotes.csv & docs/data/csv/quotes-small.csv: CSV versions of the databases.

Sync and Search

# Sync data files (SQLite, CSV, JSON) from the remote static website
zen-prompt sync https://anhldbk.github.io/zen-prompt/data/

# Lightning-fast keyword search using FTS5
zen-prompt search "success and happiness" --limit 3

Development

Install dev tools and the full local verification stack with:

uv sync --group dev

Install the git hook:

uv run pre-commit install

Run the standard local verification flow:

scripts/check

This runs:

• uv run pre-commit run --all-files
• uv run python -m pytest

Testing

Run the full suite of unit and integration tests:

uv run python -m pytest

Project Structure

• zen-prompt/: Core package containing models, spider, database logic, and pipelines.
• scripts/: Entry point bash scripts.
• docs/: Design documents, implementation plans, and exported web assets (docs/data/).
• tests/: Comprehensive test suite.

---

Vibe coded via Codex.