# Company Research CLI

> Workflow guide for using company-research as a CLI tool via Bash

- Skill: `riftwerx/company-research-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add riftwerx/company-research-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/riftwerx/company-research-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: RiftWerx (https://skillmd.com/u/riftwerx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/riftwerx/company-research-cli

---


# company-research CLI workflow

## Setup

`CH_API_KEY` must be set in the environment — not accepted as a CLI flag.

All commands output JSON to stdout; errors go to stderr with exit 1. Use `jq` to extract fields.

## Command reference

```
search-company <query> [-l/--limit N]
get-company-profile <ch-number>
list-filings <ch-number> [-c/--category STR] [--start N] [-l/--limit N]
fetch-filing <ch-number> <document-id>
get-latest <ch-number> <category>
list-zip-contents <ch-number> <document-id>
extract-xbrl-facts <local-path> [--name-prefix STR] [--include-text-facts]
clear-cache [--ch-number STR]
```

## Canonical sequence

```bash
company-research search-company "Tesco"                     # pick ch_number
company-research list-filings 00445790 --category accounts  # pick document_id
company-research fetch-filing 00445790 <document_id>        # get local_path
company-research extract-xbrl-facts <local_path>            # financial facts
```

`get-latest` shortcut — replaces `list-filings` + `fetch-filing`:
```bash
company-research get-latest 00445790 accounts
```

## Key facts

- CH numbers are zero-padded to 8 digits: `00445790` not `445790`
- `list-filings` common categories: `accounts`, `confirmation-statement`; omit `--category` to discover all
- `document_id` is an opaque UUID from `list-filings`/`get-latest` output — never construct it
- `extract-xbrl-facts` takes `local_path` (from `fetch-filing`/`get-latest` output), **not** `document_id`

## ZIP archives

When `fetch-filing`/`get-latest` returns `"is_archive": true`:
```bash
company-research list-zip-contents 00445790 <document_id>  # pick entry: is_primary or content_type
company-research extract-xbrl-facts <entry_local_path>
```

## PDF-rendered iXBRL

When `extract-xbrl-facts` returns `"render_type": "pdf_rendered"`: XBRL facts are present but narrative text is inaccessible. Check `warnings` for alternative formats.