companies-house-cli

Use ch for UK Companies House data: company search, profiles, officers, filings, PSC, charges, and insolvency.

Setup

• - INLINECODE1
• Get a free API key: https://developer.company-information.service.gov.uk/
• INLINECODE2 or add it to a local INLINECODE3

Search

• - By name: INLINECODE4
• With restrictions: INLINECODE5
• Fetch all pages: INLINECODE6
• JSON in canonical style: INLINECODE7

Company Profile

• - By number: INLINECODE8
• Force text: INLINECODE9
• Short numbers auto-pad: ch info 9215862 becomes INLINECODE11

Officers

• - List directors/secretaries: INLINECODE12
• All officers: INLINECODE13
• Order by: INLINECODE14

Filings

• - Filing history: INLINECODE15
• Filter by type: INLINECODE16
• Include document download links: INLINECODE17
• All filings: INLINECODE18

PSC (Beneficial Owners)

• - List PSC records: INLINECODE19
• All records: INLINECODE20

Search Person

• - Find a person across UK companies: INLINECODE21
• Limit enrichment fan-out: INLINECODE22
• Fetch all search pages: INLINECODE23

Charges

• - List company charges: INLINECODE24
• All charges: INLINECODE25

Insolvency

• - Check insolvency history: INLINECODE26
• Returns empty result cleanly if no history exists (not an error)

Pagination

• - List commands support: --items-per-page <n>, --start-index <n>, INLINECODE29
• INLINECODE30 fetches every page automatically
• INLINECODE31 and non-zero --start-index cannot be combined

Output

• - Defaults to text in a TTY and JSON when piped
• Canonical usage is subcommand-local flags: ch search "Revolut" --json, INLINECODE34
• Root compatibility aliases still work: ch --json search "Revolut", INLINECODE36
• Success envelope: INLINECODE37
• Error envelope: INLINECODE38
• Command metadata now lives under data.input and INLINECODE40
• Disable colour: INLINECODE41

Agent Notes

• - JSON mode writes handled errors to stdout, not stderr
• Error payloads include code, message, and INLINECODE44
• Exit codes are explicit:

• - Update any existing parsers that expected top-level input or pagination; those now live under INLINECODE51

Notes

• - API key required (free, instant signup at Companies House developer portal)
• Auth is HTTP Basic (key as username, blank password)
• Rate limit: 600 requests per 5 minutes
• Company numbers are automatically zero-padded to 8 digits
• INLINECODE52 fans out appointment requests for each match — use --match-limit on broad names to control API usage
• INLINECODE54 on filings derives document content URLs for direct PDF download