Static public essay index for paulgraham.com.
Created by @debgotwired (Deb Mukherjee).
Quick Start
1. Install
See Install above.
2. Verify Setup
paul-graham-pp-cli doctor
This checks your configuration.
3. Try Your First Command
paul-graham-pp-cli latest --limit 5
Usage
Run paul-graham-pp-cli --help for the full command reference and flag list.
Commands
articles-html
Manage articles html
paul-graham-pp-cli articles-html - Returns the static HTML essay index from paulgraham.com. The site does not expose an official JSON API; native CLI helpers parse this page and linked essay pages.
latest
paul-graham-pp-cli latest --limit 10 - List the newest essays from the canonical essay index.
list
paul-graham-pp-cli list --query startup --limit 20 - List essays, optionally filtering by title or slug.
search
paul-graham-pp-cli search startup --limit 10 - Search essay titles and slugs.paul-graham-pp-cli search "default alive" --full-text --json - Fetch matching essay pages and search full text.
read
paul-graham-pp-cli read greatwork - Read an essay by slug, URL, title, or title substring.paul-graham-pp-cli read "Founder Mode" --max-chars 2000 --json - Return extracted essay text with word count and excerpt metadata.
links
paul-graham-pp-cli links greatwork --json - Extract links from an essay page.
random
paul-graham-pp-cli random --seed 42 --json - Pick a random essay from the index.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
paul-graham-pp-cli latest --limit 5
# JSON for scripting and agents
paul-graham-pp-cli search startup --json --limit 5
# Filter to specific fields
paul-graham-pp-cli list --json --select title,url
# Dry run — show the request without sending
paul-graham-pp-cli articles-html --dry-run
# Agent mode — JSON + compact + no prompts in one flag
paul-graham-pp-cli read greatwork --agent --max-chars 2000
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.
Health Check
paul-graham-pp-cli doctor
Verifies configuration and connectivity to the API.
Configuration
Config file: ~/.config/paul-graham-essays-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Troubleshooting
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
Generated by CLI Printing Press