Install with the CLI wizard

The Whisperr wizard is a command-line tool that installs Whisperr in the project on your machine. It detects your stack, installs the SDK, wires identify() and your events, runs your build checks, and waits for the first event. Use it if you want a one-command install without connecting a coding agent. For the other ways to install, see Install with your coding agent and Install with a pull request.

Requirements

• Node.js 18.17 or later.
• A Whisperr account with onboarding completed.
• A git repository with a clean working tree. Commit or stash your changes first.

Run the wizard

In your project root:

npx @whisperr/wizard

Or point it at a directory:

npx @whisperr/wizard path/to/app

The wizard prints a code and opens https://app.whisperr.net/wizard/activate in your browser. Sign in, check that the Connection code matches, choose the app in App to connect, and click Authorize. The wizard then receives your event plan and an ingestion key for that app, and continues in the terminal.

What does the wizard change?

The wizard:

1. Detects the stack and picks the matching SDK.
2. Installs and initializes the SDK, and adds generated event wrappers.
3. Wires identify(), reset() where the stack has a logout, and a track() call for each event.
4. Runs the repository’s type check, lint and build scripts.
5. Waits for the first event from your app.

Every event ends the run as wired, with its file, or skipped, with the reason. The result is a diff in your working tree. Review it and commit it yourself.

Run the wizard once per surface: the web app, the mobile app, then the backend. Each run knows what earlier runs already wired.

Which stacks does the wizard support?

Next.js, web (JavaScript and TypeScript), React Native, Flutter, Swift, Node.js, Python and PHP.

Options

Option	What it does
--propose-only	Sends new events for approval in the dashboard instead of adding them now.
--strict-review	Reviews the finished diff more deeply.
--force	Runs without a clean git tree. You lose the safe undo.
--offline	Runs a demo with a mock event plan. No account or browser needed.
-h, --help	Shows help.
-v, --version	Shows the version.

What does the wizard read and send?

The wizard reads files only inside your repository. It blocks secret material: .env and .env.* (except .env.example and .env.sample), private keys and key stores, credential files, .aws, .ssh and .gnupg. It can run only package-manager installs, mkdir, git status, git diff and git log, and it does not edit .git or CI configuration.

The code context that the wizard needs goes to Whisperr’s model gateway. The run report goes to the Whisperr API: each event’s result and file, the verification status, and a short summary.

To discard the wizard’s changes:

git restore . && git clean -fd

Common questions

Do I need a Whisperr API key to run the wizard?

No. The wizard signs you in through the browser. You approve it for one app, and the wizard receives that app's ingestion key.

Can I undo the wizard's changes?

Yes. The wizard needs a clean git working tree, so its changes are the only changes. To discard them, run git restore . && git clean -fd.

Can the wizard read my .env files?

No. It blocks reads of .env and .env.* files (except .env.example and .env.sample), key files and credential files, and it can only run an allowlist of package-manager commands.