HookTap CLI

Send webhook events to the HookTap app straight from your terminal.

---

HookTap turns HTTP POST requests into instant iPhone push notifications, lock screen widgets, and Live Activities. hooktap is the official command-line client: a single, dependency-free binary that follows Unix conventions — it reads from stdin, plays nicely with pipes, and exits with meaningful codes.

echo "Staging deploy is live" | hooktap send --title "Deploy"

Install

macOS / Linux — curl installer:

curl -fsSL https://hooktap.me/install.sh | sh

macOS / Linux — Homebrew:

brew install HookTap/tap/hooktap

Windows — Scoop:

scoop bucket add hooktap https://github.com/HookTap/scoop-bucket
scoop install hooktap

Other methods

# With Go
go install github.com/hooktap/hooktap-cli@latest

# Or download a prebuilt binary from the releases page:
# https://github.com/HookTap/hooktap-cli/releases

Setup

Install HookTap on the App Store, open the CLI pairing screen, and run the command shown in the app:

hooktap setup --code 123456

You can also copy your webhook id manually (the YOUR_HOOK_ID part of https://hooks.hooktap.me/webhook/YOUR_HOOK_ID) and save it:

hooktap setup
# or:
hooktap config set hook_id YOUR_HOOK_ID
hooktap ping        # ok — hooktap (2026-06-22T07:14:55.993Z)

hooktap setup creates a profile, stores it in the config file, and sends a test notification unless you pass --no-test.

Usage

# Simplest form — the title is the argument
hooktap send "Build finished"

# Open the terminal UI
hooktap
hooktap tui

# Notify when a command finishes
hooktap watch -- npm run build
hooktap watch --title "Deploy" -- make deploy

# Add a body and pick the event type
hooktap send "CI failed" --body "main branch" --type push

# Pipe text from stdin — it becomes the body
echo "Prod is up" | hooktap send --title "Deploy"
cat report.txt | hooktap send "Nightly report"

# Pipe a complete JSON body verbatim (for field-mapping webhooks)
generate-payload.sh | hooktap send --raw

# Machine-readable output for scripts
hooktap send "Order #123" --json | jq .eventId

Terminal UI

Run hooktap or hooktap tui to open the interactive terminal interface:

Screen	Purpose
Send	Compose and send a push/feed/widget event
Profiles	Inspect configured profiles and the active default
Snippets	Copy-ready examples for scripts and raw JSON
Doctor	Config path, profile count, and basic diagnostics

Keyboard shortcuts: 1-4 switch screens, Tab moves between inputs, Ctrl+T cycles event types, Ctrl+S sends, q quits.

Watch commands

Use watch to run any command and receive a notification when it exits:

hooktap watch -- npm run build
hooktap watch --title "Production deploy" -- make deploy

The command output streams normally, and hooktap watch exits with the watched command's exit code.

Event types

Type	Behaviour
push (default)	Stores the event and sends an instant push notification
feed	Stores the event in the in-app feed only (no notification)
widget	Updates the lock screen / home screen widget

Flags

Flag	Short	Description
--title		Event title (alternative to the positional argument)
--body	-b	Event body text (overrides stdin)
--type	-t	push · feed · widget (default push)
--raw		Send a complete JSON body read from stdin, verbatim
--hook		Webhook id or full URL (overrides config/env)
--profile	-p	Config profile to use
--url		Base URL override (staging / self-hosting)
--json		Print the raw JSON response to stdout

Configuration

hooktap resolves each setting in this order: command-line flag → environment variable → config file.

Config file & profiles

Stored at ~/.config/hooktap/config.toml (honours XDG_CONFIG_HOME). Use named profiles to keep several webhooks side by side:

hooktap config set hook_id abc123                 # writes the default profile
hooktap config set url https://… --profile ci     # a named profile
hooktap config set type feed --profile ci
hooktap config use ci                             # change the default
hooktap config list                               # * marks the default
hooktap config path                               # print the file location

default = "ci"

[profiles.default]
hook_id = "abc123"

[profiles.ci]
url  = "https://hooks.hooktap.me/webhook/xyz"
type = "feed"

The file is written 0600 — your webhook id acts as a bearer token, so keep it private.

Environment variables

Variable	Description
HOOKTAP_HOOK_ID	Webhook id
HOOKTAP_WEBHOOK_URL	Full webhook URL (id is parsed out)
HOOKTAP_BASE_URL	Base URL override

Exit codes

Code	Meaning
0	Success
1	Network or server error
2	Usage error (missing title, unknown type, no webhook configured)
4	Rate limited (HTTP 429 — max 1 request/second; safe to retry)

Examples

Long-running command finished:

make build && echo "build ok" | hooktap send "🏗️  $(basename $PWD)" \
  || echo "build failed" | hooktap send "💥 $(basename $PWD)" --type push

Cron / monitoring:

# /etc/cron.d/disk-check
0 * * * *  df -h / | tail -1 | hooktap send "Disk usage" --profile ops

Pipe a server's JSON straight to your phone:

curl -s https://api.example.com/status | hooktap send --raw

Shell completions

# zsh
hooktap completion zsh > "${fpath[1]}/_hooktap"

# bash
hooktap completion bash > /usr/local/etc/bash_completion.d/hooktap

# fish
hooktap completion fish > ~/.config/fish/completions/hooktap.fish

Completions are context-aware: --type suggests the valid event types and --profile suggests your configured profiles.

Related

• HookTap Integrations — recipes for cURL, CI, Python, Node, and more
• HookTap Notify Action — GitHub Action wrapper

This repository is maintained by github.com/HookTap.

License

MIT — see LICENSE.