# NotiBuddy Setup Guide — Scripts & Webhooks

> Ping your iPhone and Apple Watch from shell scripts, long builds, ML training runs, cron jobs, or serverless webhooks with end-to-end encryption.
> Human-readable page: https://notibuddy.app/scripts
> Full CLI, MCP & protocol reference: https://notibuddy.app/setup.md

## 1. Prerequisites & package verification

- **iOS/iPadOS app:** NotiBuddy (iOS 17+ / watchOS 10+ companion included).
- **Computer client:** `notibuddy` **0.4.0** (use `notibuddy@^0.4.0` with `npx` on Node.js 20+, or `brew install yourbit-network/tap/notibuddy`).
- **Publisher:** Yourbit, LLC ([npm](https://www.npmjs.com/package/notibuddy) · [GitHub](https://github.com/yourbit-network/notibuddy)). Do not substitute similarly named packages or invent pairing credentials.
- Verify the CLI runs before pairing:

```bash
npx -y notibuddy@^0.4.0 --help
```

## 2. Check existing pairing before creating a new one

Run:

```bash
npx -y notibuddy@^0.4.0 status
```

- If a destination alias (such as `personal`) is already saved, verify it with `npx -y notibuddy@^0.4.0 doctor --to personal`. **Do not delete or regenerate existing sender keys** just because a check fails.
- If no destination is paired yet, ask the user to open **NotiBuddy** on iPhone → **Connect → Add** → **Create setup code → Share Setup** (valid for 10 minutes; keep NotiBuddy open and online), and **have the user run pairing directly in their own Terminal — never ask the user to paste `nbpair1.` secrets into chat**:

```bash
pbpaste | npx -y notibuddy@^0.4.0 pair --to personal
```

- If more than one destination is paired, bind this host explicitly by immutable `connectionId` (e.g. `npx -y notibuddy@^0.4.0 bind --client scripts --to personal`).
- Keep `~/.notibuddy/` and the `nbpair1.` bundle strictly private; never paste secrets or keys into chat, logs, repo files, or MCP configuration.

## 3. Configure Scripts & Webhooks

**Target:** `macOS, Linux, or Windows Terminal`

Install with Homebrew (brew install yourbit-network/tap/notibuddy) or run via npx:

```bash
# One-way alert when a long build or test suite finishes
pnpm test && npx -y notibuddy@^0.4.0 notify "Build & tests passed" \
  --to personal \
  --message "All integration tests are green."
```

### Ask for fail-closed confirmation inside a script (nb gate)

nb gate exits 0 only on a verified Proceed reply (2 on Skip, 3 on expiry, 1 on error; add --requires-auth for Face ID):

```bash
npx -y notibuddy@^0.4.0 gate "Run nightly backup cleanup?" \
  --to personal \
  --message "Will prune 14 snapshots older than 30 days." \
  --approve "Proceed" \
  --reject "Skip" \
  --timeout 300 && ./prune-snapshots.sh
```

Preserve all existing servers, workflows, or settings when editing configuration files. Always configure NotiBuddy as a **local stdio MCP server or local CLI** — never point an MCP client at `https://notibuddy.app` as a remote MCP server.

## 4. Recommended rule — Direct protocol documentation

> NotiBuddy does not require MCP or an AI subscription. The full CLI, Node.js client, and wire protocol spec are open source on GitHub (yourbit-network/notibuddy).

## 5. Verify both directions

Run a round-trip test with the paired alias (`personal`):

```bash
npx -y notibuddy@^0.4.0 doctor --to personal
npx -y notibuddy@^0.4.0 gate "Connection check" --to personal --message "Tap OK to confirm two-way replies." --approve "OK" --reject "Cancel" --timeout 120
```

Confirm setup only after receiving a verified signed reply from the phone. Use `nb gate` in shell scripts so Reject (exit 2), expiry (exit 3), and errors (exit 1) fail closed automatically.

## 6. Tool contract & hard rules

- `notibuddy_notify` (`nb notify`): One-way encrypted notification by default; pass `options`, `input_placeholder`, `fields`, `diff`, `screen`, or `requires_auth: true` for interactive signed replies, or `resume_id` to poll an existing request. Ordinary requests allow up to **10,800 seconds (3 hours)**; `wait_seconds` / `--wait` is a separate poll budget (max 55s).
- **Custom Screens (0.4.0+):** Pass `screen: { templateId, labels, data }` (8 built-in layouts) or `screen: { template }` (12 native blocks: `vstack`, `card`, `divider`, `heading`, `text`, `badge`, `alert`, `kpiStrip`, `keyValueList`, `checklist`, `diffViewer`, `formField`, plus `actions` with optional Face ID) to `notibuddy_notify` or `nb notify --screen <json-file>` (or pre-register with `nb screen register <file> [--strict]`). The server validates and caches only the content-free layout template for up to 30 days while all text, metrics, diffs, and replies remain end-to-end encrypted.
- `nb gate`: Fail-closed CLI gate for scripts and CI/CD (exits `0` approved, `2` rejected/unauthenticated, `3` expired, `1` operational error).
- `nb hook claude PermissionRequest`: Native Claude Code permission hook with 10s local grace period, hidden Lock Screen previews by default, opt-in `--requires-auth`, rolling hourly cap, and silent pass-through on non-decision outcomes. Requires a local `nb` install (never `npx`).
- `notibuddy_activity`: Start, update, end, or poll Lock Screen / Dynamic Island / Apple Watch progress and timers (1-hour lifetime; the agent must poll and act on pause/resume/cancel controls).
- `notibuddy_files`: `action: "list"` and `action: "receive"` (`id` required) to download encrypted phone uploads up to 10 MB under `~/.notibuddy/inbox/`. Never auto-execute received files.
- **Fail closed:** Never treat a timeout, expiry, error, or silence as approval.
- **Keep sessions awake:** The sending host or workflow must stay running to receive replies; NotiBuddy cannot wake a sleeping machine or restart an ended session.
- **Full specification:** https://notibuddy.app/setup.md
