tipitaka-search

A fast, zero-dependency CLI tool for searching and reading the Pali Canon (Tipiṭaka) from the Chaṭṭha Saṅgāyana Tipiṭaka Version 4.0 (CST4).

Built for AI agents and Pali scholars who need quick, precise access to canonical texts — root texts (mūla), commentaries (aṭṭhakathā), and sub-commentaries (ṭīkā).

Features

• Full-text search across the entire Pali Canon with highlighted results
• Read suttas by canonical reference (DN 15, MN 10) or by name (brahmajala, mahanidana)
• Three text layers: mūla (root), aṭṭhakathā (commentary), ṭīkā (sub-commentary)
• Comparative view: see root text alongside its commentary
• Paragraph extraction: pull specific paragraph ranges from any text
• JSON output mode for programmatic use by AI agents and scripts
• Zero dependencies: Python 3.7+ stdlib only — no pip install needed
• Beautiful terminal output with Unicode box-drawing and ANSI colors

Quick Start

1. Get the data

Clone one or both CST4 data sources:

# Per-sutta XML (recommended, 44MB, DN/MN/SN/AN)
git clone https://github.com/dhamma/cstxml.git

# Full canon XML (4.9GB, includes Vinaya, Khuddaka, Abhidhamma)
git clone https://github.com/VipassanaTech/tipitaka-xml.git

2. Run the tool

# Place the script alongside the data directories, or specify --data-dir
python3 tipitaka_search.py --data-dir ./cstxml search "paṭiccasamuppāda"

Or make it a permanent command:

# Add to your PATH
chmod +x tipitaka_search.py
ln -s $(pwd)/tipitaka_search.py /usr/local/bin/tipitaka

# Now use it anywhere
tipitaka search "paṭiccasamuppāda"

Usage

Search

Search for Pali terms across the canon:

# Basic search
tipitaka search "paṭiccasamuppāda"

# Filter by nikāya
tipitaka search "cattāri ariyasaccāni" --nikaya SN

# Search in commentaries
tipitaka search "atthasālinī" --layer att

# More context lines
tipitaka search "bojjhaṅga" --context 5

# JSON output (for AI agents / scripts)
tipitaka search "nibbāna" --json --max-results 10

Read

Read a full sutta by reference or name:

# By canonical reference
tipitaka read DN.15
tipitaka read MN.10
tipitaka read SN.22
tipitaka read AN.5

# By sutta name (partial match)
tipitaka read brahmajala
tipitaka read mahanidana
tipitaka read mahasatipatthana

# Read the commentary
tipitaka read DN.15 --layer att

# JSON output
tipitaka read MN.10 --json

List

Browse available texts:

# List everything
tipitaka list

# Filter by nikāya
tipitaka list --nikaya MN
tipitaka list --nikaya DN

Info

Show metadata about a text:

tipitaka info DN.15
tipitaka info MN.10

Output shows nikāya, file ID, Pāli name, word count, and whether commentary/sub-commentary are available.

Compare

View root text alongside its commentary:

tipitaka compare DN.15
tipitaka compare MN.10 --max-lines 80

Passage

Extract specific paragraph ranges:

# Paragraphs 96-110 of DN 15
tipitaka passage DN.15 --start 96 --end 110

# From paragraph 1 onwards
tipitaka passage MN.10 --start 1 --end 20

Reference Formats

The tool accepts flexible reference formats:

Format	Example	Meaning
NK N	DN 15	Nikāya + number
NK.N	MN.10	Dot-separated
nkN	sn22	Lowercase, no separator
NK-N	AN-5	Hyphen-separated
name	brahmajala	Sutta name (partial match)

Nikāya codes

Code	Nikāya	Texts
DN	Dīgha Nikāya	34 suttas
MN	Majjhima Nikāya	152 suttas
SN	Saṃyutta Nikāya	56 saṃyuttas
AN	Aṅguttara Nikāya	11 nipātas

Text layers

Layer	Name	Description
mul	Mūla	Root canonical text (default)
att	Aṭṭhakathā	Traditional commentary
tik	Ṭīkā	Sub-commentary

JSON Output

All commands support --json for structured output, making the tool ideal for AI agents:

# Search returns structured results
tipitaka search "dukkha" --json | python3 -c "
import json, sys
data = json.load(sys.stdin)
print(f'Found {data[\"total\"]} results')
for r in data['results'][:3]:
    print(f'  {r[\"ref\"]}: {r[\"line\"][:80]}...')
"

Data Sources

This tool works with two CST4 data repositories:

dhamma/cstxml (recommended)

• Per-sutta XML files in romanized Pali (UTF-8)
• Covers DN, MN, SN, AN with mūla, aṭṭhakathā, and ṭīkā
• ~44 MB, ~760 XML files
• Includes typo corrections and clean XML structure

VipassanaTech/tipitaka-xml

• Full Tipiṭaka in multiple scripts (Romanized, Devanagari, Thai, Myanmar, etc.)
• Includes Vinaya, Khuddaka Nikāya, and Abhidhamma
• ~4.9 GB total, romanized files in romn/ directory

The tool auto-detects available data and uses cstxml for per-sutta access when available, falling back to tipitaka-xml/romn for texts not covered by cstxml.

Architecture

tipitaka_search.py     Single-file CLI (zero dependencies)
    ├── Index builder   Scans XML files, builds name→file mapping
    ├── XML parser      Strips markup, preserves structure
    ├── Search engine   Full-text search with context
    ├── Ref resolver    Parses DN.15, brahmajala, etc.
    └── Formatters      Terminal (ANSI) and JSON output

The index is cached as .tipitaka-index.json for fast subsequent lookups. Rebuild with tipitaka index --rebuild.

About the CST4

The Chaṭṭha Saṅgāyana Tipiṭaka Version 4.0 is the digital edition of the Pali Canon published by the Vipassana Research Institute. It is based on the Sixth Buddhist Council (Chaṭṭha Saṅgāyana) edition and includes variant readings from multiple editions (Burmese, Sri Lankan, Thai, PTS).

License

MIT