parl

name	parl
description	Use the `parl` Node CLI (and the matching `lib/facilities/*.mjs` JS library) to query every public UK Parliament API and dataset — Members, Bills, Hansard, Committees, Commons / Lords divisions, oral and written questions, Early Day Motions, statutory instruments, treaties, the Register of Members' Financial Interests, Erskine May, the live annunciator, e-petitions, the SPARQL endpoint, OData, the parameterised-query browser, the Linked Data API, historic Hansard, MNIS, the explore.data.parliament.uk dataset catalogue, the All-Party Parliamentary Groups Register, the What's On calendar (sittings / sessions / procedural dates), the MPs' Guide to Procedure, the Bill Papers CSV catalogue, and the Library Feeds RSS aggregator. Use whenever a question references UK Parliament data — this is the single entry point that every per-facility skill in this repo delegates to.
license	Open Government Licence v3.0 (Crown copyright; Parliament APIs); skill text MIT.
compatibility	Requires Node 18+ (uses native fetch / URL / AbortController). Outbound HTTPS to parliament.uk hostnames. Browser-compatible — same source runs in modern browsers.
metadata	{"cli-binary":"bin/parl.mjs","library-entry":"lib/facilities/index.mjs","spec-cache":"_specs/","provenance-policy":"docs/provenance.md"}

parl — UK Parliament CLI

parl is a single Node CLI that wraps every public UK Parliament data exposure as a facility. Each facility has its own skill in skills/ under the spec-conformant short slug (members, bills, etc. — or, for the legacy ones still using the longer prefix, uk-parliament-<slug>). All of those skills delegate the actual data fetch to parl.

This file is the place to come when you need to know how to run parl, regardless of which facility you're working with. Per-facility specifics (endpoints, parameters, quirks) live in the facility's own skill.

Quick start

parl <facility> <command> [args] [--option value]
node bin/parl.mjs <facility> <command> ...      # if `parl` isn't on PATH

parl --help                       # list every facility
parl <facility> --help            # list a facility's commands
parl <facility> <command> --help  # one-line help for a command

The CLI uses kebab-case flags (--member-id 4514) that map to camel-case library kwargs (memberId: 4514). Repeated flags accumulate into arrays.

Output modes

Flag	Behaviour
--json (default)	Parsed JSON response printed pretty.
--text	Human-readable rendering (tables for lists, summaries for objects, raw string passthrough for non-JSON bodies).
--raw	Verbatim response body.
--out <path>	Stream binary downloads (PDFs, ZIPs) to disk.
--user-agent <s>	Override User-Agent for the request.
--timeout <seconds>	Override request timeout (default 30s).

Facilities

The full list (canonical name first, aliases in parens):

Facility	Skill	What it covers
members	skills/members	MPs and peers, current and historical; constituencies; parties; government / opposition posts.
bills	skills/bills	Bills through every stage including amendments and ping-pong.
committees	skills/committees	Select / Joint committees, inquiries, evidence, publications, meetings.
hansard	skills/hansard	Hansard 1988→ — debates, contributions, divisions, full-text search.
commons-votes	skills/commons-votes	Commons divisions (recorded votes).
lords-votes	skills/lords-votes	Lords divisions (Content / Not Content).
oral-questions	skills/oral-questions-and-edms	Tabled oral questions and EDMs.
wq	skills/written-questions-and-statements	Written questions, statements, daily reports.
si	skills/statutory-instruments	Statutory instruments and their procedures.
treaties	skills/treaties	Treaties laid under CRaG.
interests	skills/interests	Register of Members' Financial Interests.
em	skills/erskine-may	Erskine May (parliamentary procedure manual).
now	skills/now	Live annunciator (what's on in each chamber now).
petitions	skills/petitions	UK Parliament e-petitions.
whatson	skills/whatson	Calendar, sittings, sessions, procedural dates.
gtp	skills/guide-to-procedure	MPs' Guide to Procedure (plain-English explainers).
bp	skills/bill-papers	Bill Papers CSV catalogue + per-bill RSS.
library	skills/library-feeds	Commons Library / Lords Library / POST research-briefing RSS aggregator.
sparql	skills/sparql	Public SPARQL 1.1 endpoint over the DDP store.
odata	skills/odata	OData v4 over the same data graph.
pq	skills/parameterised-query	124 named SPARQL templates returning JSON.
lda	skills/linked-data-api	Legacy Linked Data API (Elda) datasets.
hh	skills/historic-hansard	Historic Hansard 1803–2005 (HTML site).
mnis	skills/members-data-platform	Legacy Members Data Platform.
ddpd	skills/data-parliament-uk-datasets	Catalogue of the 19 explore.data.parliament.uk datasets.
appg	skills/appg	All-Party Parliamentary Groups (HTML scrape).

Idiomatic chains

• Postcode → MP: parl pq postcode "SW1P 3JA" (one call) or parl members constituency-search then parl members constituency <id>.
• MP → recent voting: parl members search --name X --take 1 → take the id, then parl commons-votes member <id> --take 25.
• Bill → debates: parl bills search --term "X" → take billId, parl bills stages <billId>, then parl hansard search-debates --term "X".
• Committee inquiry: parl committees search --term "X" → parl committees business-search --committee-id <id> → parl committees oral-evidence-search --committee-business-id <id>.
• SI laid in date range: parl si search --laid-date-from 2026-02-16 --laid-date-to 2026-05-16 --take 500 (client-side; auto-pages).
• Annulment / praying-period date: parl whatson annulment-date --date-laid 2026-04-23 --days-in-future 40.
• Next sitting day: parl whatson next-sitting Commons --date-to-check 2026-05-16.

Library use (Node + browser)

import * as F from './lib/facilities/index.mjs';
const r = await F.members.search({ name: 'Cooper', take: 5 });

The library uses only fetch / URL / AbortController so the same source runs in Node 18+ and in modern browsers.

Provenance and naming (read this once)

The repo's focus is UK Parliament material — both Houses, the Commons / Lords Libraries, POST, the official Parliament APIs and RDF / SPARQL / OData stores. Anything else is third-party.

Skill names encode provenance tier (docs/provenance.md has the full convention):

Naming	What it means
No prefix (members, bills, hansard, treaties, si, …)	Tier 1: first-party Parliament. Authoritative.
scraped-<name>	Tier 2: data Parliament publishes only as HTML/PDF, processed by our heuristic scrapers. Authoritative upstream, heuristic interpretation.
<producer>-<name> (mysoc-twfy, tna-legislation, ec-donations, wikidata, …)	Tier 3: third-party service. Operator named by the prefix.

When you use this skill or any facility skill in an answer:

• Cite the source briefly once per paragraph — e.g. "(via bills-api.parliament.uk)" or "(per TheyWorkForYou)". Don't repeat for every clause; don't write a long formal citation unless the user asks for one.
• If you combine facilities, attribute each fact to its source. Prefer "per members: X; per mysoc-twfy: Y" over a merged sentence.
• Never up-rate confidence. Tier-2 (scraped) and tier-3 (third-party) facts must not be presented as if they came straight from Parliament's authoritative graph. Say "likely", "according to", "per …" where appropriate.
• If a record carries _field_sources (mixed-source facility), treat each field's provenance independently.

The --raw flag prints the actual URL the CLI hit; that's the canonical machine-readable source if the user asks "where did this come from".

Cross-cutting notes

• Server vs client filtering: where the upstream API has no date filter we want, the library auto-pages and applies the filter client-side, returning the same { items, totalResults } envelope plus _unfilteredTotal, _fetched, _exhausted metadata. Currently applies to treaties.search and si.search.
• Honesty about coverage: every fact returned should be backed by a tool call. The CLI prints the URL it called via --raw; cite it.
• Three RDF graphs / SPARQL endpoints: Parliament runs three RDF graphs, two public (docs/sparql-endpoints.md). DDP is what sparql fronts; DD (procedural ontology) is NOT on the public SPARQL endpoint — for procedural-business queries that come back empty, drop down to the matching REST API.
• Specs: cached OpenAPI specs live in _specs/. The probe script at scripts/probe-endpoints.sh confirms every endpoint is reachable.

Reference

• Full CLI dispatcher: bin/parl.mjs
• Per-facility library modules: lib/facilities/
• Shared HTTP layer: lib/http.mjs
• Client-side filter helper: lib/client-filter.mjs
• Repo index: ../../readme.md