# ContextStellar CLI Guide

The repository includes a zero-dependency Node.js CLI for local Claude Code prompt-scoring hooks. It is not a generic hosted API client and does not need an API key for local scoring.

## Availability

The public npm registry returned 404 for @contextstellar/cli during verification on November 6, 2026. Publication requires a maintainer's approval and registry access. Do not use or advertise `npx @contextstellar/cli` until the package is actually published and verified.

From a checkout of this project, using Node.js 20.9 or later:

```sh
node packages/cli/bin/contextstellar.mjs --help
node packages/cli/bin/contextstellar.mjs stats
```

These commands display usage or local statistics without installing hooks.

## Install local hooks

Review the effects and obtain the machine owner's permission before running:

```sh
node packages/cli/bin/contextstellar.mjs init
```

The command copies the self-contained hook into ~/.contextstellar/hook.mjs, initializes a local event store and weights if absent, backs up ~/.claude/settings.json and installs PreToolUse, PostToolUse and Stop command hooks. Existing unrelated hooks are preserved. It can replace existing ContextStellar command/HTTP hook entries. Local events, weights and cached statistics remain under ~/.contextstellar.

## Remove hooks

```sh
node packages/cli/bin/contextstellar.mjs uninstall
```

This backs up and removes ContextStellar hook entries from Claude settings. Local data is preserved; deletion of that data is a separate choice. Confirm permission before changing another person's configuration.

## Cloud integrations

For project telemetry over HTTP, use the [API reference](/docs/api-reference.md), [OpenAPI contract](/openapi.json) and [authentication guide](/docs/authentication.md). The local CLI does not establish OAuth support, hosted sync, a production sandbox or public SDK availability.
