Uspto

USPTO CLI

When to Use

Use this skill when the user asks to:

• Search for patents by keyword, inventor, assignee, CPC class, examiner, or date range
• Look up a specific patent application's metadata, prosecution history, continuity, or assignments
• Download patent documents (PDFs, DOCX, XML) from the file wrapper
• Download a full patent artifact bundle in one command (JSON + XML + PDFs + README)
• Extract structured patent text (claims, citations, abstract, description) from patent XML (grant/pgpub)
• Search or retrieve PTAB trial proceedings, decisions, appeals, or interferences
• Search petition decisions
• Browse or download bulk data products from USPTO
• Look up patent application status codes
• Build a patent family tree or get a one-shot application summary
• Export patent data to CSV, JSON, or NDJSON for analysis

Prerequisites

The uspto binary must be installed and on PATH. The user needs a USPTO API key from the ODP (Open Data Portal) at api.uspto.gov.

Install:

go install github.com/smcronin/uspto-cli/cmd/uspto@latest
# Or update an existing install:
uspto update

API Key Setup:

uspto config set-api-key your-key-here       # Save to global config
uspto config set-api-key --from-dotenv .env   # Import from .env file
uspto config show                             # Verify key status

If the user doesn't have a key: create account at https://data.uspto.gov/apis/getting-started, verify via ID.me, copy key from https://data.uspto.gov/myodp.

Output Formats

Always use -f json -q when calling the CLI programmatically:

• -f json gives a structured envelope: { ok, command, pagination, results, facets, version, error }
• -q (quiet) suppresses stderr progress messages
• Add --minify for compact JSON
• On uspto search only, add --fields to select specific response fields and save tokens

Other formats: -f table (default, wide), -f csv (flat), -f ndjson (streaming).

Exit codes: 0=OK, 1=general, 2=usage/validation, 3=auth-failure, 4=not-found, 5=rate-limited, 6=server-error.

Application Number Format

Critical: All app subcommands require bare digits -- strip all slashes, commas, country codes.

Commands Reference

Patent Bundle

Use this first when the user asks to "download a patent" and expects more than metadata. Resolves ANY identifier (app number, publication number, patent number).

uspto patent bundle US20050021049A1
uspto patent bundle 10924035 --id-type patent
uspto patent bundle 16123456 --out ./patents/my-patent

Output: 00_resolution.json, 01_associated-docs.json, 03_docs.json, 04_download-all.json, xml/, pdf/, README.md.

02_fulltext.json is created only when grant full text is available. For pending applications or other publication-only cases, the bundle skips that file and records a warning instead.

ID auto-detection order: app number, publication number, patent number. Use --id-type to override.

Patent Search

# Free-text search
uspto search "wireless sensor network" -f json -q

# Field filters
uspto search --title "neural network" --inventor "Smith" --limit 10 -f json -q
uspto search --assignee "Apple" --cpc "G06N" --granted -f json -q
uspto search --patent 10902286 -f json -q
uspto search --pub-number "US20190095759A1" -f json -q

# Date ranges
uspto search --title "battery" --filed-after 2023-01-01 --filed-before 2024-12-31 -f json -q
uspto search --title "battery" --filed-within 2y -f json -q
uspto search --granted-after 2024-01-01 -f json -q

# Pagination and export
uspto search --assignee "Tesla" --granted --all -f json -q        # All pages (up to 10,000)
uspto search --assignee "Tesla" --granted --all -f csv > out.csv   # Client-side CSV concat
uspto search --assignee "Tesla" --download csv > out.csv           # Server-side bulk export
uspto search --title "AI" --count-only -f json -q                  # Fast count only

# Advanced: POST filters and facets
uspto search --filter "applicationTypeLabelName=Utility" --facets "applicationTypeCategory" -f json -q
uspto search --title "drone" --fields "applicationNumberText,applicationMetaData.inventionTitle,applicationMetaData.patentNumber" -f json -q

All search flags: --title, --inventor, --assignee, --examiner, --applicant, --assignor, --cpc, --cpc-group, --patent, --pub-number, --publication-number, --docket, --art-unit, --reel-frame, --status, --type, --granted, --pending, --filed-after, --filed-before, --filed-within, --granted-after, --granted-before, --sort, --limit, --offset, --page, --all, --count-only, --filter, --facets, --fields, --download

Application Data

uspto app get 16123456 -f json -q          # Full record
uspto app meta 16123456 -f json -q         # Metadata only (lighter)
uspto app docs 16123456 -f json -q         # File wrapper documents
uspto app docs 16123456 --codes "rejection,allowance" -f json -q
uspto app txn 16123456 -f json -q          # Prosecution history events
uspto app cont 16123456 -f json -q         # Continuity (parents/children)
uspto app assign 16123456 -f json -q       # Assignments/ownership
uspto app attorney 16123456 -f json -q     # Attorney/agent info
uspto app pta 16123456 -f json -q          # Patent term adjustment
uspto app fp 16123456 -f json -q           # Foreign priority claims
uspto app xml 16123456 -f json -q          # Associated XML doc metadata

# Download a document by 1-based index
uspto app dl 16123456 3 -o ./office-action.pdf
uspto app dl 16123456 3 --as docx -o ./office-action.docx  # Word with full text
uspto app dl 16123456 3 --as xml -o ./office-action.tar    # Structured XML (tar)

# Download all file wrapper PDFs
uspto app dl-all 16123456 -o ./downloads/
uspto app dl-all 16123456 --codes "CLM" --from 2023-01-01 -o ./claims/
uspto app dl-all 16123456 --codes "rejection" --as docx -o ./rejections/

--codes aliases: rejection=CTNF,CTFR | allowance=NOA | claims=CLM | spec=SPEC | abstract=ABST | drawings=DRWR | ids=IDS

Grant XML Extraction (Structured Patent Text)

Parse official patent XML for structured text. Uses grant XML first, falls back to pgpub XML for pending apps.

uspto app claims 16123456 -f json -q       # Individual claims with references
uspto app citations 16123456 -f json -q    # Patent + NPL citations
uspto app abstract 16123456 -f json -q     # Abstract text
uspto app description 16123456 -f json -q  # Full specification (large)
uspto app fulltext 16123456 -f json -q     # Everything in one shot (largest)

Compound Commands

# Best "first look" command -- 5 API calls combined
uspto summary 16123456 -f json -q

# Recursive patent family tree (follows continuity chains)
uspto family 16123456 --depth 3 -f json -q

# One-shot prosecution timeline
uspto prosecution-timeline 16123456 -f json -q
uspto prosecution-timeline 16123456 --codes rejection,allowance,CLM -f json -q

PTAB

uspto ptab search --type IPR --patent 9876543 -f json -q
uspto ptab search --petitioner "Samsung" --status "Instituted" -f json -q
uspto ptab get IPR2023-00001 -f json -q
uspto ptab decisions-for IPR2022-00302 -f json -q
uspto ptab docs-for IPR2025-01319 -f json -q
uspto ptab appeals "obviousness" --limit 10 -f json -q
uspto ptab interferences --limit 10 -f json -q
# Bulk download
uspto ptab search --type IPR --download csv > ipr_proceedings.csv

Petition Decisions

uspto petition search "revival" -f json -q
uspto petition search --app 16123456 -f json -q
uspto petition get <recordId> --include-documents -f json -q

Bulk Data

uspto bulk search "patent grant" -f json -q
uspto bulk get PTGRXML --include-files --latest -f json -q
uspto bulk files PTFWPRE --limit 10 -f json -q
uspto bulk download PTGRXML ipg240102.zip -o ./data/

Status Codes

uspto status 150 -f json -q           # By code number
uspto status "abandoned" -f json -q   # By description text

Common: 150=Patented, 161=Abandoned (failure to respond), 250=Expired (maintenance fees), 30=Docketed, 41=Non-Final Action Mailed.

Workflow Patterns

Find and examine a patent

# 1. Patent number -> app number
uspto search --patent 10902286 -f json -q
# -> results[0].applicationNumberText = "16123456"

# 2. Comprehensive overview
uspto summary 16123456 -f json -q

# 3. Drill into specifics
uspto app claims 16123456 -f json -q
uspto app cont 16123456 -f json -q

Landscape / portfolio analysis

# Size the landscape
uspto search --title "solid state battery" --granted --filed-within 5y --count-only -f json -q

# Faceted analysis
uspto search --title "solid state battery" --granted --filed-within 5y --facets "applicationMetaData.firstApplicantName" -f json -q

# Full export
uspto search --assignee "Samsung" --cpc "H01M" --download csv > samsung_battery.csv

Prosecution history review

# 1. Timeline overview
uspto prosecution-timeline 16123456 -f json -q

# 2. Filter for office actions
uspto app docs 16123456 --codes "CTNF,CTFR,NOA" -f json -q

# 3. Download specific document by index
uspto app dl 16123456 3 -o ./office-action.pdf

Extracting text from office action PDFs: USPTO file-wrapper PDFs are image-based scans with NO embedded text layer (pdftotext returns empty). Use --as docx to download the Word version with full structured text:

# Download office action as DOCX (contains full structured text)
uspto app dl 16123456 3 --as docx -o ./office-action.docx

# Download all rejections as DOCX
uspto app dl-all 16123456 --codes "rejection" --as docx -o ./rejections/

# Extract text from DOCX for parsing
python -c "from docx import Document; [print(p.text) for p in Document('office-action.docx').paragraphs if p.text.strip()]"

Valid --as values: pdf (default), docx, xml (returns tar archive). Not all documents have all formats -- the error message lists available formats if your choice isn't available.

OCR fallback (if DOCX is unavailable for a document):

pdftoppm -r 300 -png ./office-action.pdf ./oa-pages
for img in ./oa-pages-*.png; do tesseract "$img" "${img%.png}" --oem 3 --psm 6; done
cat ./oa-pages-*.txt > ./office-action-ocr.txt

Parse for: 35 U.S.C. § 102/103/112, Claim(s) X-Y is/are rejected, prior art reference numbers.

Known Limitations and Gotchas

• Data coverage: ODP covers applications from 2001-01-01 onward. Older patents may return 404.
• CPC search unreliable: --cpc "H04W" may 404. Use --filter "applicationMetaData.cpcClassificationBag=H04W*" instead.
• Never combine --granted and --pending: Returns ALL 5.4M+ apps instead of the intersection.
• --granted-after is more reliable than --filed-after + --granted for issued-only date windows.
• --type flag unreliable via GET: Use --filter "applicationTypeLabelName=Design" instead.
• 6MB payload limit: Reduce --limit or use --fields to narrow response. HTTP 413 = too broad.
• Single-item endpoints return arrays: Access results[0]. Exception: summary returns results: {...} (object).
• Rate limiting is automatic: CLI handles 429 retry (3x, 5s backoff) and cross-process coordination. No sleep needed.
• Patent XML may be missing: Some records have no grant/pgpub XML. Fall back to app docs PDF workflow.
• --dry-run: Available on all commands. Shows the API URL without executing.

What This API Cannot Do

• Reverse/forward citations: ODP only gives what a patent cites (app citations), NOT what cites it. Reverse citations require PatentsView (search.patentsview.org, DIFFERENT API key).
• Disambiguated entities: No inventor/assignee clustering or co-inventor networks.
• Trademarks: Use TSDR API (tsdrapi.uspto.gov, separate key from account.uspto.gov/api-manager).
• Full-text body search: Free-text search hits titles and indexed metadata only, not specification text.

Do NOT confuse API keys: ODP (X-API-KEY, from data.uspto.gov/myodp) != PatentsView != TSDR. Completely separate auth systems.

Error Recovery

Source: smcronin/uspto-cli — distributed by TomeVault.