# Install with the CLI wizard

> Run npx @whisperr/wizard in your project to install the Whisperr SDK, wire identify and your events, verify the build and wait for the first event.

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](/agents/) and [Install with a pull request](/guides/pull-request-agent/).

## 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:

```bash
npx @whisperr/wizard
```

Or point it at a directory:

```bash
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:

```bash
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.

Source: https://docs.whisperr.net/guides/wizard/