Command-line client for HiQ Cortex — look up real LCA emission factors from 18 life-cycle inventory databases (ecoinvent, BAFU, USLCI, ELCD, EF, worldsteel, HiQLCD …) and 24,000+ published EPDs.
Carbon-footprint answers have to come from real inventory data. A remembered "steel is about 2 kg CO₂e/kg" is useless to an LCA practitioner: the real value depends on database, version, system model, production route and geography, and varies several-fold across those dimensions. This CLI gets you the actual number with its basis and a link back to the dataset.
Apache-2.0. The client is thin — search, ranking and match-quality scoring all run server-side; this package posts your query and renders what comes back.
A single self-contained executable — nothing else has to be on the machine, no Node, no Python, no runtime of any kind.
macOS / Linux
curl -fsSL https://download.hiq.earth/cli/hiq-cortex/install.sh | shWindows
irm https://download.hiq.earth/cli/hiq-cortex/install.ps1 | iexServed from a CDN that is reachable from mainland China, where github.com and raw.githubusercontent.com are both blocked; GitHub Releases stays the source of truth and mirrors within a minute of each tag.
Both installers detect the platform, verify the checksum, and drop hiq-cortex
into a per-user directory (~/.local/bin, %LOCALAPPDATA%\Programs\hiq-cortex)
— no sudo, no admin. HIQ_CORTEX_VERSION, HIQ_CORTEX_INSTALL and
HIQ_CORTEX_BASE_URL (mirror origin) override the defaults.
Prebuilt binaries for macOS (arm64 / x64), Linux (x64 / arm64) and Windows (x64) are also attached to every release directly, with a checksums file.
Where Node is already there — agent hosts, CI, an existing project — the same CLI ships on npm, which skips the download step entirely:
npx @hiq-ai/hiq-cortex-cli doctorhiq-cortex login # QR sign-in, no registration needed
hiq-cortex search "304 不锈钢"▸ 中厚板, 304不锈钢,混合技术 [匹配度 medium]
参考流: 中厚板, 304不锈钢 单位: kg
基准: HiQLCD · 1.5.0 · CUT_OFF · CN
GWP: 5.2839 kg CO2-Eq
链接: https://www.hiqlcd.com/dataset/HiQLCD/1.5.0/CUT_OFF/...
Every row carries its basis (database · version · system model · geography) and a link to the dataset page. A number without its basis is not usable.
hiq-cortex search "<你的原话>" [--sources BAFU,Ecoinvent] # 材料 / BOM 行 → 候选数据集
hiq-cortex search-datasets --source hiqlcd --ver 1.5.0 --model CUT_OFF --queries "电力,天然气" # 确定性目录候选(低延迟)
hiq-cortex verify-flows --source hiqlcd --ver 1.5.0 --flows "id:kg,id2,…" # 基本流 id(+单位)核验
hiq-cortex search-flows --source hiqlcd --ver 1.5.0 --queries "二氧化碳,天然气" # 基本流候选(BM25+向量,中英)
hiq-cortex verify-datasets --source hiqlcd --ver 1.5.0 --datasets "id:kWh,id2,…" # 上游数据集 id(+模型/单位/下架)核验
hiq-cortex list # 全部子命令(--json 出 schema)
hiq-cortex describe aggregate-datasets # 某个子命令的参数
hiq-cortex doctor # 凭据来源 + 连通性自检
hiq-cortex login / logoutverify-flows is for dataset authoring, not querying: it checks elementary-flow
ids — and optionally the unit your row uses — against the catalog the calculation
actually reads for that source coordinate (/api/relic/flows/verify). Identity is
(name, compartment, unit); a uuid alone cannot tell sm3 from m3, and a wrong id
is silent downstream. --flows takes id[:unit],… or @file (JSON array of strings
or {id, unit}); --ver is required because verification is per coordinate. Exit 2
when anything is missing or a unit mismatches, so scripts can branch without parsing.
Commercial sources return counts only without an entitlement.
search-datasets is the deterministic first pass for dataset authoring. It queries the relic
catalog directly, keeps the canonical datasetRef, source/version/model, reference unit and
location variants, and accepts a batch of strings or {query, locations?, activityTypes?, identity?} records through --queries. It does no LLM translation or ranking. Use the slower
search command only when the direct catalog pass has no defensible candidate.
search-flows returns elementary-flow candidates for dataset authoring (column H): relic
/flows/search, BM25 over names/synonyms/CAS/formula plus a Qwen3-Embedding vector branch, so a
Chinese item name finds its English catalog entry. --queries takes a,b,… or @file (JSON array
of strings or {query, compartment?, identity?}); output keeps input order. identity is opaque
correlation metadata: the CLI never sends it to relic and copies it onto the corresponding result,
so an authoring workflow can search with a translated alias without losing the source-row identity.
verify-datasets does for upstream dataset ids (UPR column I) what verify-flows does for
elementary flows: /datasets/verify answers whether the id exists at that coordinate, under which
system models, what its reference unit is and whether it is still published. --datasets takes
id[:unit],… or @file (JSON array of strings or {id, model?, unit?}); an id that exists only
under another model comes back found=false with availableModels. Exit 2 on any missing,
unit-mismatched or unpublished row.
Beyond the static REST commands, tool subcommands are generated at runtime from the server's tool catalog — there is no schema copy in this package to drift when the server adds a field. At the time of writing:
| Command | What it does |
|---|---|
lookup-datasets |
dataset_key → GWP、基准、链接 |
aggregate-datasets |
队列 GWP 分布、百分位定位(行业对标) |
aggregate-indicators |
非 GWP 的 LCIA 指标(酸化、富营养化…) |
process-hotspot |
单数据集的工序级热点 |
epd-search |
检索已发布 EPD(EPDItaly / ECO Platform / EPD Norge) |
epd-peer-benchmark |
EPD 同类分布与离群判定 |
Escape hatch: hiq-cortex call <native_tool_name> --args '<json>'.
search takes 20–40 seconds — the server searches the catalogs and verifies
every hit. That is normal, not a hang; retrying in parallel only adds load.
Two ways, env wins when both are present:
hiq-cortex login # 浏览器点一次授权,凭据存 ~/.config/hiq-cortex/credentials.json (600)
export HIQ_API_KEY=sk_xxx # 服务端 / CISign-in returns your own SSO credential, so the visible data scope equals your
account's — including any commercial databases you have entitlements for.
logout removes the stored file.
New logins request cortex_data consent, describing LCA data and organization
knowledge reading. The returned credential is the user's full SSO login, not a
technically read-only or Wiki-scoped token; the consent page must state this.
Server authorization still applies to every request. Organization Wiki access is
provided by the independent cortex-org-wiki CLI and skill.
An absolute XDG_CONFIG_HOME selects the native credential store at
$XDG_CONFIG_HOME/hiq-cortex/credentials.json for login, use and logout. When
explicitly selected, an empty store does not fall back to another account's
legacy credential. This also lets test environments use an isolated fake login.
Credentials from the older Python client (~/.hiq/credentials.json) are still
read, so you don't have to sign in again after switching.
Human-readable text by default. --json for machines:
- stdout on success:
{"ok":true,"tool":…,"text":…}（REST 搜索用结构化data） - stderr on failure:
{"ok":false,"kind":…,"message":…}
Exit codes — branch on these rather than parsing messages:
| Code | Meaning |
|---|---|
0 |
ok |
2 |
凭据缺失/失效 |
3 |
参数不合法 |
4 |
服务端拒绝(含权益不足;换参数重试没用) |
5 |
连不上服务端 |
1 |
未知 |
| 层 | 内容 | 要求 |
|---|---|---|
| 目录层 | 18 个库的清单、版本、系统模型、LCIA 覆盖;数据集名称、单位、地域 | 无需权益 |
| 免费库数值 | BAFU、USLCI、ELCD、EF、AusLCI、NEEDS、ozLCI、worldsteel、USDA、bioenergiedat、recycledplastics | 任一有效凭据 |
| 商业库数值 | ecoinvent、HiQLCD、HiQLCD-AL、CALCD、CarbonMinds、Agri-footprint | 需对应数据包权益 |
无权益时返回受限标记与 purchase_url（这不是报错）。免费库覆盖面不小 ——
BAFU 在欧洲语境下是很好的默认选择，worldsteel 覆盖钢铁，USLCI / USDA 覆盖美国供应链。
- 凭据只从环境变量或
login落盘的文件读取，不写进任何其他地方，也不在输出中回显。 - 查询只发往
x.hiqlcd.com（海科数据 API），不发往任何第三方。 - 不收集、不上传本地文件、目录结构或对话内容。
npm install
npm run build # tsc → dist/ (the npm channel)
npm test # build + real CLI/HTTP fixture + clean npm package install
npm run dev # tsx src/cli.ts
npm run build:bin # bun --compile → dist-bin/ (every platform, needs bun)build:bin cross-compiles all five targets from whichever machine runs it;
only the Darwin binaries need a Mac, to be codesigned. Releases build them on a
macOS runner for that reason.
The version lives in package.json alone — prebuild stamps it into
src/version.ts, because a single-file binary has no manifest to read at
runtime.
CLI lifecycle tests use a loopback OAuth server and fake tokens in temporary
XDG_CONFIG_HOME directories. They verify isolated login/logout, local help,
and a clean npm installation. Keep the parent test process's XDG_CONFIG_HOME
isolated as CI does; runtime config loads when modules are imported.