@lexbuild/cli

This package is part of the LexBuild monorepo, a tool that converts U.S. legislative XML into structured Markdown optimized for AI, RAG pipelines, and semantic search. See the monorepo for full documentation, architecture details, and contribution guidelines.

It provides the CLI entry point for downloading and converting legal and civic texts. Built on @lexbuild/core for shared parsing and rendering infrastructure, and also @lexbuild/usc for United States Code support. Implementing support for additional sources (CFR, state statutes) is planned.

Install

Install globally

npm install -g @lexbuild/cli

Run directly with npx:

npx @lexbuild/cli download --all
npx @lexbuild/cli convert --all

Quick Start

# Download and convert all 54 titles
lexbuild download --all && lexbuild convert --all

# Start small — download and convert Title 1
lexbuild download --titles 1 && lexbuild convert --titles 1

# Download and convert a range
lexbuild download --titles 1-5 && lexbuild convert --titles 1-5

Commands

`lexbuild download`

Fetch U.S. Code XML files from the OLRC.

lexbuild download --titles 1           # Single title
lexbuild download --titles 1-5,8,11    # Range + specific titles
lexbuild download --all                # All 54 titles (single bulk zip)

Option	Default	Description
`--titles <spec>`	—	Title(s) to download: `1`, `1-5`, `1-5,8,11`
`--all`	—	Download all 54 titles
`-o, --output <dir>`	`./downloads/usc/xml`	Output directory
`--release-point <id>`	current	OLRC release point

`lexbuild convert`

Convert downloaded XML to Markdown.

lexbuild convert --titles 1                          # By title number
lexbuild convert --all                               # All downloaded titles
lexbuild convert ./downloads/usc/xml/usc01.xml       # Direct file path
lexbuild convert --titles 1 -g chapter               # Chapter-level output
lexbuild convert --titles 1 -g title                 # Title-level output (single file)
lexbuild convert --titles 1 --link-style canonical   # OLRC website links
lexbuild convert --titles 42 --dry-run               # Preview without writing

Option	Default	Description
`--titles <spec>`	—	Title(s) to convert
`--all`	—	Convert all titles in input directory
`-i, --input-dir <dir>`	`./downloads/usc/xml`	Input directory for XML files
`-o, --output <dir>`	`./output`	Output directory
`-g, --granularity <level>`	`section`	`section`, `chapter`, or `title`
`--link-style <style>`	`plaintext`	`plaintext`, `canonical`, or `relative`
`--no-include-source-credits`	—	Exclude source credits
`--no-include-notes`	—	Exclude all notes
`--include-editorial-notes`	—	Include editorial notes only
`--include-statutory-notes`	—	Include statutory notes only
`--include-amendments`	—	Include amendment notes only
`--dry-run`	—	Parse and report without writing files
`-v, --verbose`	—	Verbose logging

Output

Section granularity (default):

output/usc/title-01/chapter-01/section-1.md

Chapter granularity (-g chapter):

output/usc/title-01/chapter-01.md

Title granularity (-g title):

output/usc/title-01.md

Each file includes YAML frontmatter (identifier, title, chapter, section, status, source credit) followed by the statutory text with bold inline numbering. Title-level output includes enriched frontmatter with chapter_count, section_count, and total_token_estimate.

Performance

The full U.S. Code — all 54 titles, 60,000+ sections, ~85 million estimated tokens — converts in about 20-30 seconds on modern machines. SAX streaming keeps memory bounded for even the largest titles (100MB+ XML).

Documentation

License

MIT