Skip to content

docs: clarify the headroom CLI is pip-only; npm headroom-ai is the TS SDK - #1585

Merged
chopratejas merged 1 commit into
headroomlabs-ai:mainfrom
tenderdeve:docs/1470-npm-cli-clarity
Jun 30, 2026
Merged

chopratejas merged 1 commit into
headroomlabs-ai:mainfrom
tenderdeve:docs/1470-npm-cli-clarity

Conversation

@tenderdeve

Copy link
Copy Markdown
Contributor

Description

npm install headroom-ai doesn't give you the headroom CLI — it's the TypeScript SDK (a library, no bin). The README's "Get started" and "Install" blocks listed the npm install next to the pip install and then immediately ran headroom wrap claude, so Node/Windows users reasonably expected npm to provide the CLI and hit 'headroom' is not recognized. This spells out the split: CLI = pip, SDK = npm.

The hnswlib/MSVC half of the report was already fixed on main in #1499 (moved hnswlib to the optional [vector] extra), so this PR only addresses the npm-CLI confusion.

Closes #1470

Type of Change

  • Documentation update

Changes Made

  • README "Get started" + "Install" blocks: annotate that pip ships the headroom CLI and npm headroom-ai is the TS SDK with no CLI; note the headroom commands come from the pip install.
  • docs/content/docs/installation.mdx: state the TS SDK does not install the headroom CLI.

Testing

  • Manual testing performed

Test Output

Docs-only change. Verified against the source of truth:
- pyproject.toml: [project.scripts] headroom = "headroom.cli:main"  (CLI entry point is Python-only)
- sdk/typescript/package.json: name "headroom-ai", no "bin" field  (SDK, no CLI)

Real Behavior Proof

  • Environment: repo main @ HEAD
  • Exact command / steps: read [project.scripts] in pyproject.toml and the bin field in sdk/typescript/package.json
  • Observed result: headroom console script is defined only by the Python package; the npm package has no bin, so npm install headroom-ai provides no headroom command — matching the issue.
  • Not tested: n/a (no code paths changed)

Review Readiness

  • I have performed a self-review
  • This PR is ready for human review

Checklist

  • My code follows the project's style guidelines
  • I have performed a self-review of my code
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings

The Get started and Install blocks listed 'npm install headroom-ai' next to
the pip install and immediately followed with 'headroom wrap claude', implying
the npm package provides the CLI. It doesn't — npm headroom-ai is the
TypeScript SDK (a library, no bin), and the headroom CLI ships only via the
PyPI package. Spell out the split so Windows/Node users don't hit
'headroom is not recognized' after an npm-only install.

Closes headroomlabs-ai#1470
@github-actions

Copy link
Copy Markdown
Contributor

PR governance

This PR follows the template and is marked ready for human review.

@github-actions github-actions Bot added the status: ready for review Pull request body is complete and the author marked it ready for human review label Jun 30, 2026
@chopratejas
chopratejas merged commit abab3cc into headroomlabs-ai:main Jun 30, 2026
2 checks passed
JerrettDavis pushed a commit to peterlodri-sec/headroom that referenced this pull request Jul 14, 2026
… SDK (headroomlabs-ai#1585)

## Description

`npm install headroom-ai` doesn't give you the `headroom` CLI — it's the
TypeScript SDK (a library, no `bin`). The README's "Get started" and
"Install" blocks listed the npm install next to the pip install and then
immediately ran `headroom wrap claude`, so Node/Windows users reasonably
expected npm to provide the CLI and hit `'headroom' is not recognized`.
This spells out the split: CLI = pip, SDK = npm.

The hnswlib/MSVC half of the report was already fixed on main in headroomlabs-ai#1499
(moved hnswlib to the optional `[vector]` extra), so this PR only
addresses the npm-CLI confusion.

Closes headroomlabs-ai#1470

## Type of Change

- [x] Documentation update

## Changes Made

- README "Get started" + "Install" blocks: annotate that pip ships the
`headroom` CLI and npm `headroom-ai` is the TS SDK with no CLI; note the
`headroom` commands come from the pip install.
- `docs/content/docs/installation.mdx`: state the TS SDK does not
install the `headroom` CLI.

## Testing

- [x] Manual testing performed

### Test Output

```text
Docs-only change. Verified against the source of truth:
- pyproject.toml: [project.scripts] headroom = "headroom.cli:main"  (CLI entry point is Python-only)
- sdk/typescript/package.json: name "headroom-ai", no "bin" field  (SDK, no CLI)
```

## Real Behavior Proof

- Environment: repo main @ HEAD
- Exact command / steps: read `[project.scripts]` in pyproject.toml and
the `bin` field in sdk/typescript/package.json
- Observed result: `headroom` console script is defined only by the
Python package; the npm package has no `bin`, so `npm install
headroom-ai` provides no `headroom` command — matching the issue.
- Not tested: n/a (no code paths changed)

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status: ready for review Pull request body is complete and the author marked it ready for human review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Windows installation fails due to hnswlib / MSVC requirement and npm package does not provide CLI

2 participants