CLI

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

Sign in once

Run this from a terminal on the machine you will scan from. It prints a short code, opens your browser, and stores a credential once you approve it there.

bash

npx vibebeacon@latest login

After that, scan --upload, upload, review and the MCP server all use the stored credential, so you do not need to pass --key again. Full detail on the credential and the alternative one-time tokens is on the Tokens and login page.

The command you want

bash

npx vibebeacon@latest scan --upload

That reads the credential login stored. In CI, inject VIBEBEACON_API_KEY through your secret store. The optional --key syntax below uses a placeholder; keep real credentials out of prompts and logs:

bash

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

Look before you upload

Leave off --upload to see the file first. Nothing is sent and you get a JSON file you can read.

bash

npx vibebeacon@latest scan --out vibebeacon.json

Commands

findings

CLI 0.4.1+: reads the app score, current findings and verification limits. Use --json for agents.

scan

Reads the project, writes the manifest, uploads it if you asked.

upload

Uploads a manifest already on disk, without scanning again.

review

Fetches the fix plan for an app and prints it grouped by band, with the command and the AI review prompt for each.

login

Signs in from a terminal and stores a credential. The CLI and the MCP server both read it.

logout

Deletes the stored credential from this machine.

whoami

Prints the account, plan and app count behind the stored credential or --key.

init

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

bash

npx vibebeacon@latest init

Many apps at once

--all treats a folder and its immediate child folders as candidate projects, matching each on package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, Gemfile or composer.json, and skips node_modules, .git and other dot-folders. It prints one line per project: created, updated, paused or skipped with a reason, and keeps going past a failure in any one project.

bash

npx vibebeacon@latest scan --all . --upload

Reviewing what to fix

review fetches the same fix plan the app page shows, grouped into Fix now, Fix soon, When convenient, Dev tooling and No fix yet, with the upgrade command and the AI review prompt for each package. Pass --name to pick an app when you have more than one.

bash

npx vibebeacon@latest review

bash

npx vibebeacon@latest review --name "My app" --mode apply --upload

Needs vibebeacon 0.4.1

--mode and --upload on review, and the findings command, need CLI 0.4.1 or later. In 0.4.0, review has --name and --json only. Run npm view vibebeacon version to see what npm serves. On 0.4.0, copy the fix prompt from the app page, which offers the same modes.

Review only is the default. --mode apply authorises the listed compatible fixes after evidence checks; major or breaking changes still require approval. --upload adds explicit consent for the documented scan payload and VibeBeacon destination. This command prints a handoff; it does not apply changes itself.

Results and read-only agent access

Findings and the new review controls require CLI 0.4.1 or later. Run npm view vibebeacon version first. If npm still serves 0.4.0, review findings in the web app.

shell

npx vibebeacon@latest findings --name "My app" --json

Read current findings and the real score explanation without uploading. Upload output distinguishes inventory refresh from alert transitions and lists changed IDs and reasons. Read the scan results and JSON contract for pending processing, missing baselines, scope changes and evidence limits.

Checking who you are

bash

npx vibebeacon@latest whoami

Prints the account email, plan and app count behind the stored credential, or says “Not logged in” if there is none. logout deletes the stored credential:

bash

npx vibebeacon@latest logout

Flags on scan and upload

Flag	What it does
--upload	Send the manifest to VibeBeacon. Without it nothing leaves your machine.
--key <key>	Your API key. Falls back to VIBEBEACON_API_KEY, then the credential stored by login.
--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.
--watch	Re-scan and re-upload when a package file or lockfile changes.
--debounce <ms>	Delay before watch mode re-scans. Defaults to 1000.
--no-dev	Exclude dev-only dependencies. They are included by default, shown as their own "Dev tooling" band.
--single	Read this folder only. By default the scan reads every lockfile in the project, up to three folders deep.
--include-dev	Kept for compatibility. Dev dependencies are already included by default, so this does nothing.
--group <name>	Assign the app to this group. Creates the group if it does not exist.
--tag <tag>	Add a tag. Repeat the flag to add more than one.
--all <dir>	Scan every project under this folder instead of the current one. See below.
--json	Print one JSON document: the manifest locally, or the upload result with --upload. Not available with --watch or --all.
--api <url>	Point at a different host. Only useful for self-hosted or testing.

upload takes --key, --api, --group, --tag, --json and --file (the manifest to send, defaults to vibebeacon.json) rather than re-scanning.

Excluding dev dependencies

Dev-only dependencies are scanned by default and shown as their own Dev tooling band, separate from production alerts. Leave them out entirely with:

bash

npx vibebeacon@latest scan --upload --no-dev

This reduces coverage. An omitted dependency is not a verified fix. Development classification does not prove a package cannot affect builds, CI or runtime.

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

The scan reads every folder of your project, not just the one you run it in: up to three levels down, skipping node_modules, build output, hidden folders and any folder that is its own git repository. A frontend and a backend with a lockfile each are one app, and both lockfiles are read. It prints how many it read and from how many folders. Pass --single for the old behaviour of reading the current folder only. Folder names and paths never leave your machine, whichever you choose.

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

Versions come from the lockfile where one exists, so they are the exact versions you have resolved in the lockfile, not proof of deployment or execution. 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*, other than the .env.example/.env.sample/.env.template variants, which it reads for variable names only, never values. 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 command did what you asked, including the upload if you asked for one.
1 anything went wrong: the project could not be read, the manifest was rejected, or authentication or upload failed. Human errors go to stderr; --json writes one safe error document on stdout. A pending upload is accepted with exit 0, not a claim that processing finished.

Verify what you install

The published vibebeacon package has no runtime dependencies. dist/cli.js is one self-contained file, so installing it pulls one tarball rather than a tree of packages that could change under you.

Check provenance for the exact version you install. CLI 0.4.0 was published without an attestation. A later version number alone does not prove provenance. The npm panel must identify a build and source commit for that release. See Verify us.

shell

npm audit signatures

npm audit signatures reports verified registry signatures and verified attestations across your tree.
A registry signature does not prove a public source build. The source repository is private, and CLI 0.4.0 has no provenance attestation.
Inspect the published files with npm pack vibebeacon --dry-run. This lists the tarball contents; it does not independently verify our private source.

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 was not accepted. Check it on the API keys settings page, or run npx vibebeacon@latest login again. Remove any old --key or VIBEBEACON_API_KEY override first.
402: this app would be past your free one and there is no subscription yet. The message carries a checkout link.
413: the manifest is over 512 KB or over 2000 dependencies. Try --no-dev, or scan a smaller scope, only if that coverage is intended. Excluded packages are not verified fixes.
429: more than 60 requests a minute on one key, or more than 10 new apps in a day. The message includes how long to wait.