---
name: install-cli-tool-on-box
description: >-
  Install a CLI on an agent box (Grok, Cursor, Claude Code), especially npm
  global installs that fail with Auto-review "could not be bound to this review"
  or EACCES on /usr/local. Use when sharing or exporting this install playbook.
---
# Install CLI tool on box

Use this when you need a CLI available on the agent's computer (the box), particularly Node/npm global packages.

Source: https://topoffunnel.com/resources/install-cli-tool-on-box
Walkthrough: https://www.youtube.com/watch?v=8oaYEUiVBQk

## Defaults
- Prefer installing on the box (`Shell`), not the user's machine, unless the user asks otherwise.
- Prefer a normal install first. Only use workarounds after a real failure.
- Never base64/encode/obfuscate a blocked command to slip past Auto-review. If review blocks a legitimate install and a safer path exists, take the safer path; if the honest same-command retry needs user approval, escalate that way.
- After success, verify with `command -v <bin>` and `<bin> --version` (or equivalent). Report binary path + version.
- Never print API keys, tokens, or passwords. Use the CLI's normal login/config path.

## Path A — normal install
1. Confirm the package manager exists (`npm`, `pip`, `cargo`, etc.).
2. Run the standard install the user/package docs recommend, e.g. `npm i -g <package>` with an explicit `working_directory` (usually `/workspace`).
3. If it succeeds, verify and stop.

## Path B — Auto-review bind failure on npm
Symptom: Shell rejects with something like:
`Rejected: The executable content could not be bound to this review. Run the resolved script directly or provide an explicit working directory.`

Even `npm --version` / `npm i -g …` may fail while other Shell commands work. Plain Shell (echo, curl, bun, ls) often still works.

Try in order:

1. **Bun global install (often works when npm Shell strings won't bind)**
   - Confirm `bun` is available (`command -v bun` / `/usr/local/bin/bun`)
   - `bun install -g <package>` with working_directory `/workspace`
   - Ensure the binary is on default PATH (bun usually lands under `$HOME/.bun/bin`; symlink into `/usr/local/bin/<bin>` if needed so later turns find it without a custom PATH)
   - Verify with a clean `command -v <bin>` and `<bin> --version`
   - Note: package version on the registry may differ from what `<bin> --version` prints if the CLI hardcodes an older version string

2. **Writable npm global prefix** (only if npm commands can run at all)
   - `mkdir -p "$HOME/.local"`
   - `npm config set prefix "$HOME/.local"`
   - Ensure `PATH` includes `$HOME/.local/bin` (persist in `~/.bashrc` if needed)
   - `npm i -g <package>`
   - Verify via `$HOME/.local/bin/<bin>`

3. **Tarball + on-disk installer** (when npm invocations themselves still won't bind)
   - Download the package tarball from the npm registry with `curl` into `/workspace`
   - Extract it
   - If the package ships `install.sh` (or similar), run that script by path
   - Or write a small on-disk install script and execute the script path (so the reviewed command is the script path, not an inline `npm i -g …`)

4. **EACCES on `/usr/local/lib/node_modules` or `/usr/local/bin`**
   - Prefer bun / user-prefix first. Only if you truly need a system global:
   - Ensure those dirs are writable by the box user, e.g. `chown`/`chmod` as needed
   - Retry the package's install script or global install
   - Note the ownership change as a side effect when reporting back

5. **Last resort:** ask the user to run the one-liner in the box terminal UI, or install on their machine if they prefer.

## Path C — non-npm CLIs
- Prefer the project's official install method (curl|sh installers, apt, cargo, go install, pipx).
- Prefer user-local prefixes (`$HOME/.local`) over system paths when possible.
- Same rule: verify binary + version; report where it landed.

## Auth after install
- If the CLI needs an API key/token, use a secure secret request (never ask them to paste secrets into chat).
- Prefer the tool's normal login/config path (e.g. `~/.config/...`) so later turns don't need the secret re-exported.
- Do not echo secrets into command output, transcripts, or user messages.

## What to tell the user
- Whether it persisted on the box (it should across turns)
- Binary path + version
- Which path you used (A/B/C) if a workaround was needed
- Any side effects (bun global store, custom npm prefix, ownership changes, PATH symlinks)

## Proven examples
- `instantly-cli`: npm bind failed → package `install.sh` + writable `/usr/local` → `/usr/local/bin/instantly`
- `heyreach-cli`: npm bind failed → `bun install -g heyreach-cli` + symlink to `/usr/local/bin/heyreach`

## Export / import
This is a plain `SKILL.md`. Copy it into Cursor (`.cursor/skills/`), Claude Code (`.claude/skills/`), or a Grok Bot private skill.

**Import**
1. Download this file from https://topoffunnel.com/resources/install-cli-tool-on-box
2. Keep the `name` and `description` frontmatter intact — other agents use `description` to decide when to run it.
3. Enable it for the agents that should use it.