The bot installs as @hanzo/bot: npm's bot is someone else's package

Every install, update and removal line said bot@latest or -g bot, which on npm is an unrelated third-party package. @hanzo/bot is ours and ships the bot and hanzo-bot commands. Co-authored-by: Hanzo Dev <[email protected]>
2026-10-24 20:09:02 +00:00 · 2026-09-27 16:06:03 -07:00
parent 4e6e00755c
commit 00aae8beec
15 changed files with 31 additions and 31 deletions
@@ -613,7 +613,7 @@ kill -9 <PID> # last resort
 Ensure the global `bot` CLI is installed and matches the app version:
 ```bash
 bot --version
-npm install -g bot@<version>
+npm install -g @hanzo/bot@<version>
 ```

 ## Debug Mode
@@ -818,7 +818,7 @@ bot gateway restart
 From git → npm:

 ```bash
-npm install -g bot@latest
+npm install -g @hanzo/bot@latest
 bot doctor
 bot gateway restart
 ```
@@ -100,8 +100,8 @@ Runtime requirement: **Node >= 22**.

 ```bash
 # Recommended: global install (npm/pnpm)
-npm install -g bot@latest
-# or: pnpm add -g bot@latest
+npm install -g @hanzo/bot@latest
+# or: pnpm add -g @hanzo/bot@latest

 # Onboard + install the service (launchd/systemd user service)
 bot onboard --install-daemon
@@ -60,13 +60,13 @@ curl -fsSL https://hanzo.bot/install.sh | bash -s -- --no-onboard
 If you already have Node:

 ```bash
-npm install -g bot@latest
+npm install -g @hanzo/bot@latest
 ```

 If you have libvips installed globally (common on macOS via Homebrew) and `sharp` fails to install, force prebuilt binaries:

 ```bash
-SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g bot@latest
+SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g @hanzo/bot@latest
 ```

 If you see `sharp: Please add node-gyp to your dependencies`, either install build tooling (macOS: Xcode CLT + `npm install -g node-gyp`) or use the `SHARP_IGNORE_GLOBAL_LIBVIPS=1` workaround above to skip the native build.
@@ -74,7 +74,7 @@ If you see `sharp: Please add node-gyp to your dependencies`, either install bui
 Or:

 ```bash
-pnpm add -g bot@latest
+pnpm add -g @hanzo/bot@latest
 ```

 Then:
@@ -114,7 +114,7 @@ Tip: if you don’t have a global install yet, run repo commands via `pnpm bot .

 The installer supports two methods:

- `npm` (default): `npm install -g bot@latest`
+- `npm` (default): `npm install -g @hanzo/bot@latest`
 - `git`: clone/build from GitHub and run from a source checkout

 ### CLI flags
@@ -32,7 +32,7 @@ What it does (high level):
 - Detect OS (macOS / Linux / WSL).
 - Ensure Node.js **22+** (macOS via Homebrew; Linux via NodeSource).
 - Choose install method:
-  - `npm` (default): `npm install -g bot@latest`
+  - `npm` (default): `npm install -g @hanzo/bot@latest`
  - `git`: clone/build a source checkout and install a wrapper script
 - On Linux: avoid global npm permission errors by switching npm’s prefix to `~/.npm-global` when needed.
 - If upgrading an existing install: runs `bot doctor --non-interactive` (best effort).
@@ -84,7 +84,7 @@ What it does (high level):

 - Ensure Node.js **22+** (winget/Chocolatey/Scoop or manual).
 - Choose install method:
-  - `npm` (default): `npm install -g bot@latest`
+  - `npm` (default): `npm install -g @hanzo/bot@latest`
  - `git`: clone/build a source checkout and install a wrapper script
 - Runs `bot doctor --non-interactive` on upgrades and git installs (best effort).

@@ -7,7 +7,7 @@ description: "Node.js + npm install sanity: versions, PATH, and global installs"

 Bot’s runtime baseline is **Node 22+**.

-If you can run `npm install -g bot@latest` but later see `bot: command not found`, it’s almost always a **PATH** issue: the directory where npm puts global binaries isn’t on your shell’s PATH.
+If you can run `npm install -g @hanzo/bot@latest` but later see `bot: command not found`, it’s almost always a **PATH** issue: the directory where npm puts global binaries isn’t on your shell’s PATH.

 ## Quick diagnosis

@@ -55,9 +55,9 @@ rm -rf ~/bot
 5) Remove the CLI install (pick the one you used):

 ```bash
-npm rm -g bot
-pnpm remove -g bot
-bun remove -g bot
+npm rm -g @hanzo/bot
+pnpm remove -g @hanzo/bot
+bun remove -g @hanzo/bot
 ```

 6) If you installed the macOS app:
@@ -111,8 +111,8 @@ If you used a profile, delete the matching task name and `~\.bot-<profile>\gatew

 ### Normal install (install.sh / npm / pnpm / bun)

-If you used `https://hanzo.bot/install.sh` or `install.ps1`, the CLI was installed with `npm install -g bot@latest`.
-Remove it with `npm rm -g bot` (or `pnpm remove -g` / `bun remove -g` if you installed that way).
+If you used `https://hanzo.bot/install.sh` or `install.ps1`, the CLI was installed with `npm install -g @hanzo/bot@latest`.
+Remove it with `npm rm -g @hanzo/bot` (or `pnpm remove -g` / `bun remove -g` if you installed that way).

 ### Source checkout (git clone)

@@ -24,7 +24,7 @@ Notes:
  curl -fsSL https://hanzo.bot/install.sh | bash -s -- --install-method git --no-onboard
  ```
  The installer will `git pull --rebase` **only** if the repo is clean.
- For **global installs**, the script uses `npm install -g bot@latest` under the hood.
+- For **global installs**, the script uses `npm install -g @hanzo/bot@latest` under the hood.

 ## Before you update

@@ -40,11 +40,11 @@ Notes:
 Global install (pick one):

 ```bash
-npm i -g bot@latest
+npm i -g @hanzo/bot@latest
 ```

 ```bash
-pnpm add -g bot@latest
+pnpm add -g @hanzo/bot@latest
 ```
 We do **not** recommend Bun for the Gateway runtime (WhatsApp/Telegram bugs).

@@ -169,11 +169,11 @@ Runbook + exact service labels: [Gateway runbook](/gateway)
 Install a known-good version (replace `<version>` with the last working one):

 ```bash
-npm i -g bot@<version>
+npm i -g @hanzo/bot@<version>
 ```

 ```bash
-pnpm add -g bot@<version>
+pnpm add -g @hanzo/bot@<version>
 ```

 Tip: to see the current published version, run `npm view bot version`.
@@ -72,7 +72,7 @@ sudo apt-get install -y nodejs
 Recommended on servers: npm global install.

 ```bash
-npm i -g bot@latest
+npm i -g @hanzo/bot@latest
 bot --version
 ```

@@ -176,7 +176,7 @@ More: [Linux](/platforms/linux)
 ## 7) Updates

 ```bash
-npm i -g bot@latest
+npm i -g @hanzo/bot@latest
 bot doctor
 bot gateway restart
 bot health
@@ -11,7 +11,7 @@ Native Linux companion apps are planned. Contributions are welcome if you want t
 ## Beginner quick path (VPS)

 1) Install Node 22+  
-2) `npm i -g bot@latest`  
+2) `npm i -g @hanzo/bot@latest`  
 3) `bot onboard --install-daemon`  
 4) From your laptop: `ssh -N -L 18789:127.0.0.1:18789 <user>@<host>`  
 5) Open `http://127.0.0.1:18789/` and paste your token
@@ -15,7 +15,7 @@ running (or attaches to an existing local Gateway if one is already running).
 You need Node 22+ on the Mac, then install `bot` globally:

 ```bash
-npm install -g bot@<version>
+npm install -g @hanzo/bot@<version>
 ```

 The macOS app’s **Install CLI** button runs the same flow via npm/pnpm (bun not recommended for Gateway runtime).
@@ -46,7 +46,7 @@ The macOS app expects a global `bot` CLI install to manage background tasks.

 Alternatively, install it manually:
 ```bash
-npm install -g bot@<version>
+npm install -g @hanzo/bot@<version>
 ```

 ## Troubleshooting
@@ -128,7 +128,7 @@ Replace `youruser` with the account you created, and the IP with your VM's IP.
 Inside the VM:

 ```bash
-npm install -g bot@latest
+npm install -g @hanzo/bot@latest
 bot onboard --install-daemon
 ```

@@ -24,8 +24,8 @@ Start conservative:
 - A second phone number (SIM/eSIM/prepaid) for the assistant

 ```bash
-npm install -g bot@latest
-# or: pnpm add -g bot@latest
+npm install -g @hanzo/bot@latest
+# or: pnpm add -g @hanzo/bot@latest
 ```

 From source (development):
@@ -62,11 +62,11 @@ iwr -useb https://hanzo.bot/install.ps1 | iex
 Alternative (global install):

 ```bash
-npm install -g bot@latest
+npm install -g @hanzo/bot@latest
 ```

 ```bash
-pnpm add -g bot@latest
+pnpm add -g @hanzo/bot@latest
 ```

 ## 2) Run the onboarding wizard (and install the service)