companies-house-cli

UK Companies House CLI — search companies, profiles, officers, filings, PSC, charges, insolvency, and agent-friendly JSON output aligned with rail-cli and tf...

Security Scan

The skill's requirements, instructions, and install specification align with a CLI wrapper for UK Companies House and request only the expected API key and binary.

Purpose & Capability

Name/description match the requested binary ('ch') and the declared primary credential (COMPANIES_HOUSE_API_KEY). The requested binary and API key are appropriate for a Companies House CLI.

Instruction Scope

SKILL.md only instructs the agent to run the 'ch' CLI with subcommands and flags, describes expected JSON envelopes and exit codes, and tells the user how to supply the Companies House API key; it does not direct reading unrelated files, exfiltration, or access to other system credentials.

Install Mechanism

Install uses an npm package (@shan8851/companies-house-cli) that creates the 'ch' binary — this is expected for a Node-based CLI but carries the usual moderate risk of npm packages (arbitrary install/run scripts).

Credentials

Only COMPANIES_HOUSE_API_KEY is declared as the primary credential and is justified by the CLI's need to authenticate to the Companies House API; no unrelated secrets or config paths are requested.

Persistence & Privilege

Skill is not always-enabled and is user-invocable; it does not request elevated or persistent privileges beyond normal operation and does not modify other skills or system-wide agent settings.

Assessment

This skill appears coherent for accessing Companies House data. Before installing: verify the npm package publisher and review the package source (or install in a sandbox), pin a specific package version, and avoid placing your COMPANIES_HOUSE_API_KEY in broadly shared environments. Remember npm packages can run scripts at install time — if you cannot audit the package, consider running it in an isolated environment. Note: the agent can invoke the skill autonomously by default, so keep your API key limited in scope and monitor usage (rate limit ~600 requests/5 minutes).

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

Setup

• npm install -g @shan8851/companies-house-cli
• Get a free API key: https://developer.company-information.service.gov.uk/
• export COMPANIES_HOUSE_API_KEY=your_key or add it to a local .env

Search

• By name: ch search "Revolut"
• With restrictions: ch search "Revolut" --restrictions active-companies
• Fetch all pages: ch search "Revolut" --all
• JSON in canonical style: ch search "Revolut" --json

Company Profile

• By number: ch info 09215862
• Force text: ch info 09215862 --text
• Short numbers auto-pad: ch info 9215862 becomes 09215862

Officers

• List directors/secretaries: ch officers 09215862
• All officers: ch officers 09215862 --all
• Order by: ch officers 09215862 --order-by appointed_on

Filings

• Filing history: ch filings 09215862
• Filter by type: ch filings 09215862 --type accounts
• Include document download links: ch filings 09215862 --type accounts --include-links
• All filings: ch filings 09215862 --all

PSC (Beneficial Owners)

• List PSC records: ch psc 09215862
• All records: ch psc 09215862 --all

Search Person

• Find a person across UK companies: ch search-person "Nik Storonsky"
• Limit enrichment fan-out: ch search-person "Nik Storonsky" --match-limit 5
• Fetch all search pages: ch search-person "Nik Storonsky" --all

Charges

• List company charges: ch charges 09215862
• All charges: ch charges 09215862 --all

Insolvency

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

Pagination

• List commands support: --items-per-page <n>, --start-index <n>, --all
• --all fetches every page automatically
• --all 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, ch info 09215862 --text
• Root compatibility aliases still work: ch --json search "Revolut", ch --text info 09215862
• Success envelope: { ok, schemaVersion, command, requestedAt, data }
• Error envelope: { ok, schemaVersion, command, requestedAt, error }
• Command metadata now lives under data.input and data.pagination
• Disable colour: ch --no-color search "Revolut"

Agent Notes

• JSON mode writes handled errors to stdout, not stderr
• Error payloads include code, message, and retryable
• Exit codes are explicit:
  • 0 success
  • 2 bad input or not found
  • 3 auth, upstream, or rate-limit failures
  • 4 internal failures
• Update any existing parsers that expected top-level input or pagination; those now live under data

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
• search-person fans out appointment requests for each match — use --match-limit on broad names to control API usage
• --include-links on filings derives document content URLs for direct PDF download