CLI

One command reads your package files, builds the manifest and uploads it. It needs Node 20 or newer and installs nothing permanently.

The command you want

bash

npx vibebeacon@latest scan --upload

This reads VIBEBEACON_API_KEY from the environment. To pass the key inline instead:

bash

npx vibebeacon@latest scan --upload --key vb_live_your_key_here

Look before you upload

If you would rather see the file first, leave off --upload. Nothing is sent and you get a JSON file you can read.

bash

npx vibebeacon@latest scan --out vibebeacon.json

Commands

scan

Reads the project, writes the manifest, uploads it if you asked. This is the one you will use.

init

Prints the prompt template so you can paste it into an AI tool, and writes a starter config if you want one.

bash

npx vibebeacon@latest init

Flags

Flag	What it does
--upload	Send the manifest to VibeBeacon. Without it nothing leaves your machine.
--key <key>	Your API key. Falls back to the VIBEBEACON_API_KEY environment variable.
--out <path>	Where to write the file. Defaults to ./vibebeacon.json.
--name <name>	App name. Defaults to the name field in package.json or the folder name.
--kind <kind>	One of web, api, mobile, desktop, cli, other. Defaults to web.
--watch	Re-scan and re-upload when a package file or lockfile changes.
--include-dev	Include dev dependencies. They are included by default but suppressed in alerts.
--dry-run	Print the manifest to stdout and write nothing.
--json	Machine-readable output, for CI.
--api-url <url>	Point at a different host. Only useful for self-hosted or testing.

Keeping it fresh while you work

Watch mode re-scans when a package file or lockfile changes and uploads only when the component list actually differs. It is quiet, and it is the easiest way to stay current during a week of heavy dependency work.

bash

npx vibebeacon@latest scan --upload --watch

What it reads

Source	Files
npm	package.json, package-lock.json, pnpm-lock.yaml, yarn.lock
PyPI	requirements.txt, poetry.lock, uv.lock, Pipfile.lock
Go	go.mod
crates.io	Cargo.lock
RubyGems	Gemfile.lock
Packagist	composer.lock
Runtimes	.nvmrc, .node-version, .python-version, engines in package.json, Dockerfile FROM lines
Hosting	vercel.json, netlify.toml, fly.toml, railway.json

Versions come from the lockfile where one exists, so they are the exact versions you have installed. Where only a range is available, the range is stripped to its base version and the entry is flagged unresolved, which makes matching more conservative.

What it refuses to read

No .env files, ever

The scanner works from an allow list of file names. It will not open .env, .env.local or anything matching .env*. It does not read source files, migrations or SQL. It sends no file paths, only the manifest file name. See the privacy page for the full list.

Exit codes

0 the scan worked, and the upload worked if you asked for one.
1 something went wrong reading the project. The error names the file.
2 the upload was rejected. Usually a bad key, or a plan limit. The message says which.

If it fails

No lockfile: run your package manager install once, then scan again. Without a lockfile you get ranges, not exact versions.
401: the key is wrong or revoked. Create a new one under Settings, API keys.
402: this app would be past your free one and there is no subscription yet. The response carries a checkout link.
413: the manifest is over 512 KB or over 2000 dependencies. Scan the app rather than a monorepo root.
429: more than 60 requests a minute on one key. The response includes a Retry-After.