Run without installing via npx helpshelf <command>.
Commands
| Command | What it does |
|---|---|
helpshelf | Scan and activate in one step — the default for first-time setup |
helpshelf init | Create the .helpshelf/ config directory. Runs entirely locally. |
helpshelf scan | Analyse your codebase and write a snapshot |
helpshelf push | Upload the snapshot and any markdown docs to your agent |
helpshelf sync | Re-scan and re-push — use this after changes |
helpshelf status | Show your agent's state: knowledge count, last scan |
helpshelf score | Report your AI legibility score |
helpshelf screenshot | Capture screenshots of your running app |
Common options
scan
npx helpshelf scan [options]| Option | Effect |
|---|---|
-d, --dir <path> | Project directory to scan (default .) |
-o, --output <path> | Snapshot output path (default .helpshelf/snapshot.json) |
--no-readme | Skip README parsing |
--no-deps | Skip dependency analysis |
--no-api | Skip API route detection |
--no-env | Skip environment variable detection |
--verbose | Show detailed output |
--quiet | Suppress output, for scripting |
push
npx helpshelf push [options]| Option | Effect |
|---|---|
--email <email> | Your HelpShelf account email |
--domain <domain> | Your app's domain, used for the help center URL |
--docs-dir <path> | Directory of markdown docs to include (default .helpshelf/docs) |
--site <hash> | Push to an existing site |
--api-key <key> | Use an existing API key |
--dry-run | Show what would be pushed without sending it |
--dry-run is worth using the first time, so you can see exactly what leaves your machine.
score
npx helpshelf scoreTakes --api-url if you're pointing at a non-default environment.
Attribution
--source <slug> is accepted on the root command, scan, and push. It tags where you came from — used when you've arrived from a specific tool or campaign. It's optional and affects nothing about your agent.
init doesn't accept it, since it never contacts the API.
Shipping docs alongside code
push picks up markdown files from .helpshelf/docs by default. If you keep handwritten docs in your repo, point --docs-dir at them and they'll be pushed as curated content on every sync — docs that version with your code.