Skip to main content

​
Install or PATH problems

Symptoms: wrapper: command not found, wrong binary.
  1. Confirm install completed and wrapper --version works in a new shell.
  2. For the curl installer, ensure $HOME/.wrapper/bin (or WRAPPER_INSTALL_DIR) is on your PATH.
  3. Re-run the installer or brew reinstall heycupola/tap/wrapper.

​
brew upgrade succeeded but wrapper --version is old

Homebrew and the curl installer can both be present. The curl copy at $HOME/.wrapper/bin/wrapper is prepended to PATH, so it shadows Homebrew.
  1. Run which -a wrapper. The first path is the binary --version reports.
  2. To stay on curl, re-run curl -fsSL https://wrapper.sh/install | bash.
  3. To stay on Homebrew, remove $HOME/.wrapper and the PATH line the installer added to your shell profile, then open a new terminal.

​
Homebrew says Xcode is outdated

Wrapper’s Homebrew formula installs a prebuilt binary. It does not compile Swift or require Xcode. Homebrew itself still refuses to run when the Xcode Command Line Tools on the Mac are older than Homebrew expects.
  1. Update Command Line Tools: xcode-select --install or Software Update.
  2. Or skip Homebrew and use the curl installer above.
The curl installer does not go through Homebrew, so it is unaffected.

​
Every-terminal wrap not running

Symptoms: wrapper status is empty after install.
  1. Run wrapper share (or wrapper install once if you want every terminal wrapped).
  2. Confirm wrapper status shows a live session.
  3. Check that WRAPPER_DISABLE is unset if you expected the optional install snippet.

​
Sign-in fails

Run wrapper auth login again. If the browser still cannot complete sign-in, contact support without including tokens or terminal content.

​
authorization_pending during wrapper auth login

Expected while waiting for browser approval. Keep the command running until you approve or deny the request.

​
Local attach denied

  1. Confirm wrapper status shows a live session.
  2. Prefer wrapper attach / --id over guessing ports.
  3. Check wrapper logs --follow.
Local attach uses the loopback token. Convex is not required. Remote share still needs wrapper auth login and Pro.

​
Relay share says Pro is required

Upgrade to Pro (99/yearor99/year or 15/month) from dashboard billing. Yearly is the featured price. Attach from the same computer remains available without Pro. See Pricing.

​
P2P does not come up

The terminal title starts at relay and changes to p2p when the direct data channel opens. If it stays on relay, the session is still working through the authenticated Fly relay.
  1. Run wrapper logs --follow on host and viewer.
  2. Confirm both sides use the same session and current CLI version.
  3. Test from two real networks. CI and local sandboxes often cannot reproduce NAT traversal.
  4. Set WRAPPER_P2P=0 to force relay-only mode while diagnosing.
If an open P2P channel drops, Wrapper waits briefly for a transient disconnect to recover, then switches input and output back to the relay. Look for p2p data channel failed; using relay fallback in the viewer log.

​
Session access is denied (relay)

Confirm the session id and enter the current share code when prompted. Codes are case-insensitive and expire when the host unshares. Knowing the session id alone is not enough. Owners skip the code; guests do not.

​
Controls or HUD missing

Wrapper prints controls once and uses the terminal title as its HUD. Press Ctrl+\ to reveal role-specific controls. If your terminal hides titles, use Ctrl+\ then ? for an inline status line. Check that WRAPPER_HUD is not off.

​
Still stuck

Gather non-sensitive details only:
Redact tokens, share codes, paths, and terminal contents before sending anything to support.
Last modified on September 17, 2026