Agent-first command line client for the EPO OPS 3.2 API — search patents, read claims, walk patent families, check legal events, watch your quota. Built-in guardrails keep bad queries from burning your quota; every command speaks JSON.
中文文档 · 国内镜像：Gitee（synced with GitHub）
The EPO publishes the world's richest patent data through its OPS API —
and ships no command-line tool for it. Existing clients are libraries, not
CLIs. epo-ops-cli is a small, dependency-light CLI built for the agent era:
give any AI agent (Claude Code, Codex, Cursor, Copilot, …) this repository
and say "install per AGENTS.md" — that is the whole install guide. Humans
can of course just type the commands.
pip install epo-ops-cli # or: pip install . from a clone
epo setup # paste your free Consumer Key/Secret once
epo search "txt=coffee" --n 5Get free credentials at developers.epo.org →
My Apps. Credentials are stored in ~/.epo/ops_config.json and never leave
your machine except to the EPO authentication endpoint.
| Command | What it does |
|---|---|
epo search "<CQL>" --n 10 |
Search with titles + abstracts |
epo citations <PN> |
Who cites this patent (forward citations) |
epo abstracts <PN>... |
Batch-fetch abstracts (up to 20) |
epo claims <PN> |
Claims text (EP/WO) |
epo description <PN> |
Description text (EP/WO) |
epo family <PN> |
Patent family members |
epo legal <PN> |
Legal events |
epo usage |
Today's official quota consumption |
CQL fields: ti= title, ab= abstract, pa= applicant, in= inventor,
txt= full text (quote multi-word), pd= publication date, ct= cited-by.
Wildcards work (spher*), as do AND/OR/NOT, pd within "2020" and the
official prox operator. The full annotated catalogue lives in
docs/CQL-FIELDS.md.
- Whitelist before requests — an invalid field (
abs=,NEAR, …) is rejected locally with the correct spelling in the message. Nothing is sent, nothing is spent. - Coverage awareness — claims/description exist only for EP/WO documents;
asking for a CN document returns a clear
skippednote, not a 404. - Fair-use manners — bulk abstracts go 10 per request with a pause between batches; search ranges are capped; no blind automatic retries.
- Credential hygiene — tokens are cached (your secret only ever travels to the EPO auth endpoint); every request is recorded in a local usage log.
Every data command takes --json. The output contract is frozen: exit codes
0 ok / 1 business error (JSON error object with a hint) / 2 usage
error; stdout carries data, stderr carries diagnostics; JSON field names only
ever get added. Details: docs/OUTPUT-CONTRACT.md.
epo search "ti=ice AND pa=\"lg electronics\"" --json | python -m json.toolAI agents: start from AGENTS.md — it contains the full install-audit-verify protocol and contribution rules for agent feedback.
from epo_ops_cli.core.client import OpsClient
from epo_ops_cli.services.search import SearchService
c = OpsClient() # reads ~/.epo/ops_config.json
hits = SearchService(c).search_with_abstracts('ti="ice maker"', 100)
print(hits["total"], len(hits["refs"]))espacenet-cli drives the Espacenet web channel instead of the OPS API — no key needed, adds PDF download and CSV export. Use it as the fallback when your key isn't approved yet; the two tools share design and conventions.
OPS is a free, registered service of the EPO subject to fair-use rules. This is an independent, non-official tool with no affiliation to the EPO. Large-scale retrieval belongs on the official bulk datasets, not on loops over this CLI.
Patent-searchers (no code required), doc writers, testers and coders are all welcome — see CONTRIBUTING.md and the claimable items in ROADMAP.md. AI agents can contribute too, via the protocol in AGENTS.md.