epo-ops-cli

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.

中文文档

Why this exists

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.

Quickstart

pip install .            # from a clone (PyPI release planned — see ROADMAP)
epo setup                # paste your free Consumer Key/Secret once
epo search "txt=coffee" --n 5

Get 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.

Commands

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.

Guardrails (this tool spends your quota carefully)

• 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 skipped note, 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.

For agents and scripts

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.tool

AI agents: start from AGENTS.md — it contains the full install-audit-verify protocol and contribution rules for agent feedback.

Library use

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"]))

The sibling project

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.

Compliance

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.

Contributing

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.

License

Apache-2.0