Self Install Span Coding Hooks on macOS

Last updated: June 1, 2026

Before you start

  • A Mac running macOS 13 or later

  • Admin access (sudo)

  • Your Span auth token (provided by your Span administrator)

    • NOTE: this needs to be global auth token and not PAT (see instructions here)

  • Your work email

Step 1: Download the files

Save both files into the same folder on your Mac (e.g. ~/Downloads/):

šŸ’” When downloading, you might see a warning that the file "can't be scanned for viruses." This is normal for shell scripts. The script is safe: its only function is to install coding-hooks-latest.pkg and save your auth token and work email locally. Click "Download anyway" to continue.

Step 2: Run the install

Open the Terminal app, cd into the folder where you downloaded the files, then paste the command below. Replace <VERSION> with the version number from your downloaded pkg filename, and <TOKEN> and <EMAIL> with your values:

cd <path/to/folder>     # e.g. cd ~/Downloads
sudo bash macos-with-sudo-access.sh \
  --pkg coding-hooks-<VERSION>.pkg \
  --token <TOKEN> \
  --email <EMAIL>

Enter your Mac password when prompted.

āœ… Done when you see: Result: 11/11 checks OK

Step 3: Clean up (optional)

Once the health check passes, the downloaded files are no longer needed. From the folder where you saved them, run:

rm coding-hooks-*.pkg macos-with-sudo-access.sh

(If you cd'd into the folder in Step 2, you are already there.)

Verify anytime

~/.span/bin/span-health

Uninstall

sudo bash "/Library/Application Support/app.span.coding-hooks/uninstall.sh"

Troubleshooting

  • Error: must run as root (use sudo). Re-run the command with sudo at the start.

  • Error: --pkg path not found: ... The pkg file is not in the expected location. Make sure you cd'd into the folder where you saved the pkg (run ls coding-hooks*.pkg to confirm), then re-run the command.

  • Error: --email does not look like an email address: ... Provide a valid email address like you@yourcompany.com.

  • Error: --token ... is required. Re-run with the Span auth token provided by your Span administrator.

  • span-health shows delivery-log: no log yet This is expected on a fresh install, no hook events have flowed through yet. Use Claude Code or Cursor briefly, then re-run ~/.span/bin/span-health; the warning will clear.

  • span-health shows delivery-log ... error(s) Usually clears within a few minutes. If the count continues to grow, contact the Span team.

If you are stuck on an issue not listed here, please share the full Terminal output with the Span team.