gh2discord 0.1.0__tar.gz

gh2discord-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

gh2discord-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,18 @@
+name: tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.9", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest tests/ -q

gh2discord-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/

gh2discord-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ozan Eski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gh2discord-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: gh2discord
+Version: 0.1.0
+Summary: One-command GitHub to Discord notifications: manage repo webhooks that post straight to your Discord channels.
+Project-URL: Homepage, https://github.com/ozaneski13/gh2discord
+Project-URL: Issues, https://github.com/ozaneski13/gh2discord/issues
+Author: Ozan Eski
+License: MIT
+License-File: LICENSE
+Keywords: cli,discord,github,notifications,webhook
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gh2discord
+
+Wire GitHub repos to Discord channels with one command.
+
+Discord can render GitHub webhook payloads natively — no bot, no middleware.
+The only friction is the manual setup: create a Discord webhook, copy the URL,
+open every repo's settings, paste the URL with a magic `/github` suffix.
+**gh2discord** automates the GitHub side and remembers your Discord channels,
+so tracking a new repo becomes:
+
+```bash
+gh2discord track owner/repo
+```
+
+## Install
+
+```bash
+pipx install gh2discord   # recommended
+# or
+pip install gh2discord
+```
+
+Zero runtime dependencies. Python 3.9+.
+
+## Setup (once)
+
+1. In Discord: **Channel settings → Integrations → Webhooks → New Webhook**,
+   copy the webhook URL.
+2. Register it:
+
+```bash
+gh2discord channel add general https://discord.com/api/webhooks/<id>/<token> --default
+```
+
+3. Authenticate with GitHub — any one of:
+   - `gh` CLI already logged in (nothing to do; the token is picked up automatically), or
+   - `GITHUB_TOKEN` / `GH_TOKEN` environment variable.
+     - Classic PAT: `repo` or `admin:repo_hook` scope.
+     - Fine-grained PAT: **Webhooks (write)** + **Metadata (read)** on the repos you track.
+
+You can only track repos you administer — GitHub allows webhook management
+for repo admins only.
+
+## Usage
+
+```bash
+gh2discord track owner/repo                     # default channel, all events
+gh2discord track owner/repo --events push,release,issues,pull_request
+gh2discord track owner/repo --channel alerts    # per-repo channel
+gh2discord list                                 # tracked repos
+gh2discord status                               # live hook health (last delivery)
+gh2discord ping owner/repo                      # end-to-end delivery test
+gh2discord untrack owner/repo                   # remove the hook
+```
+
+`track` is idempotent: run it twice and you get one hook, not two. It also
+repairs broken hooks in place (wrong content type, disabled, or stale events).
+If the repo already has Discord hooks pointing at *different* webhooks,
+gh2discord warns and leaves them alone unless you pass `--force`, which
+retargets one and deletes the rest.
+
+Multiple channels work without any bot: register each channel's webhook once
+(`channel add`), then route repos with `--channel`.
+
+```bash
+gh2discord channel add releases https://discord.com/api/webhooks/<id>/<token>
+gh2discord track owner/lib --channel releases --events release
+```
+
+## Notes
+
+- Config lives at `%APPDATA%\gh2discord\config.json` (Windows) or
+  `~/.config/gh2discord/config.json` (Linux/macOS). Discord webhook URLs are
+  secrets — the file is written with owner-only permissions on POSIX; don't
+  commit it anywhere.
+- `--events all` (the default) sends everything GitHub emits; Discord silently
+  ignores event types it can't render. Use an explicit list for quieter channels.
+- GitHub returns 404 (not 403) when your token lacks webhook access to a repo —
+  if a repo you own reports "not found", check your token scopes first.
+
+## Roadmap
+
+- `--bot` mode: create the Discord channel + webhook automatically (bot token).
+- Polling mode for repos you don't administer (releases/commits feeds).
+- Org-wide webhook helper for organization accounts.
+
+## License & Attribution
+
+MIT © [Ozan Eski](https://github.com/ozaneski13) — free for everyone and every
+use, personal or commercial. The one requirement (per the MIT license terms):
+if you copy, modify, or redistribute this code or a substantial portion of it,
+you must keep the copyright notice — credit **Ozan Eski / gh2discord** and
+link back to this repository.

gh2discord-0.1.0/README.md

@@ -0,0 +1,93 @@
+# gh2discord
+
+Wire GitHub repos to Discord channels with one command.
+
+Discord can render GitHub webhook payloads natively — no bot, no middleware.
+The only friction is the manual setup: create a Discord webhook, copy the URL,
+open every repo's settings, paste the URL with a magic `/github` suffix.
+**gh2discord** automates the GitHub side and remembers your Discord channels,
+so tracking a new repo becomes:
+
+```bash
+gh2discord track owner/repo
+```
+
+## Install
+
+```bash
+pipx install gh2discord   # recommended
+# or
+pip install gh2discord
+```
+
+Zero runtime dependencies. Python 3.9+.
+
+## Setup (once)
+
+1. In Discord: **Channel settings → Integrations → Webhooks → New Webhook**,
+   copy the webhook URL.
+2. Register it:
+
+```bash
+gh2discord channel add general https://discord.com/api/webhooks/<id>/<token> --default
+```
+
+3. Authenticate with GitHub — any one of:
+   - `gh` CLI already logged in (nothing to do; the token is picked up automatically), or
+   - `GITHUB_TOKEN` / `GH_TOKEN` environment variable.
+     - Classic PAT: `repo` or `admin:repo_hook` scope.
+     - Fine-grained PAT: **Webhooks (write)** + **Metadata (read)** on the repos you track.
+
+You can only track repos you administer — GitHub allows webhook management
+for repo admins only.
+
+## Usage
+
+```bash
+gh2discord track owner/repo                     # default channel, all events
+gh2discord track owner/repo --events push,release,issues,pull_request
+gh2discord track owner/repo --channel alerts    # per-repo channel
+gh2discord list                                 # tracked repos
+gh2discord status                               # live hook health (last delivery)
+gh2discord ping owner/repo                      # end-to-end delivery test
+gh2discord untrack owner/repo                   # remove the hook
+```
+
+`track` is idempotent: run it twice and you get one hook, not two. It also
+repairs broken hooks in place (wrong content type, disabled, or stale events).
+If the repo already has Discord hooks pointing at *different* webhooks,
+gh2discord warns and leaves them alone unless you pass `--force`, which
+retargets one and deletes the rest.
+
+Multiple channels work without any bot: register each channel's webhook once
+(`channel add`), then route repos with `--channel`.
+
+```bash
+gh2discord channel add releases https://discord.com/api/webhooks/<id>/<token>
+gh2discord track owner/lib --channel releases --events release
+```
+
+## Notes
+
+- Config lives at `%APPDATA%\gh2discord\config.json` (Windows) or
+  `~/.config/gh2discord/config.json` (Linux/macOS). Discord webhook URLs are
+  secrets — the file is written with owner-only permissions on POSIX; don't
+  commit it anywhere.
+- `--events all` (the default) sends everything GitHub emits; Discord silently
+  ignores event types it can't render. Use an explicit list for quieter channels.
+- GitHub returns 404 (not 403) when your token lacks webhook access to a repo —
+  if a repo you own reports "not found", check your token scopes first.
+
+## Roadmap
+
+- `--bot` mode: create the Discord channel + webhook automatically (bot token).
+- Polling mode for repos you don't administer (releases/commits feeds).
+- Org-wide webhook helper for organization accounts.
+
+## License & Attribution
+
+MIT © [Ozan Eski](https://github.com/ozaneski13) — free for everyone and every
+use, personal or commercial. The one requirement (per the MIT license terms):
+if you copy, modify, or redistribute this code or a substantial portion of it,
+you must keep the copyright notice — credit **Ozan Eski / gh2discord** and
+link back to this repository.

gh2discord-0.1.0/docs/DESIGN.md

@@ -0,0 +1,129 @@
+# gh2discord — Design
+
+**Date:** 2026-08-04
+**Status:** Approved (v0.1 scope)
+
+## Goal
+
+One-command setup for GitHub → Discord notifications. Today the flow is manual:
+create a Discord channel webhook, copy its URL, open the GitHub repo settings,
+add a webhook pointing at `<discord-url>/github`. gh2discord automates the
+GitHub side and remembers Discord channels, so tracking a new repo becomes:
+
+```
+gh2discord track owner/repo
+```
+
+Distributable tool (PyPI), not a personal script. Anyone with a GitHub token
+and a Discord webhook can use it against their own repos and servers.
+
+## Non-goals (v0.1)
+
+- Tracking repos the user does not administer (would require polling; out of scope).
+- Creating Discord channels/webhooks via bot token (roadmap, phase 2).
+- A hosted service or GitHub App. This is a local CLI.
+
+## Mechanism
+
+Discord natively renders GitHub webhook payloads when the GitHub webhook
+targets `https://discord.com/api/webhooks/<id>/<token>/github`. No middleware
+is needed. The tool only manages GitHub repository webhooks via the REST API.
+
+## CLI surface
+
+```
+gh2discord channel add <name> <discord-webhook-url> [--default]
+gh2discord channel list
+gh2discord channel remove <name>
+gh2discord channel default <name>
+gh2discord track <owner/repo> [--channel <name>] [--events e1,e2 | --events all] [--force]
+gh2discord untrack <owner/repo>
+gh2discord list
+gh2discord status [<owner/repo>]
+gh2discord ping <owner/repo>
+```
+
+- `track` is idempotent: if the repo already has a hook pointing at the target
+  URL with `content_type: json`, correct events, and active state, nothing is
+  written; otherwise the hook is repaired in place (PATCH) instead of creating
+  a duplicate. Any *other* hook targeting a Discord webhook (with or without
+  the `/github` suffix — a bare Discord URL is always a broken GitHub hook)
+  counts as a conflict: the tool warns and aborts unless `--force`, which
+  retargets the first conflicting hook and deletes the rest. When the exact
+  hook already exists alongside extra Discord hooks, `track` reports them as
+  a warning and `--force` deletes them.
+- `--events` defaults to `all` (GitHub `*`; Discord silently ignores event
+  types it cannot render).
+- `untrack` deletes the hook (matched by recorded id, falling back to target
+  URL) and removes the local record. If no matching hook exists on GitHub,
+  the local record is still cleared (persisted) and the command exits 1.
+- `status` reads live hook state incl. `last_response` (delivery health).
+- `ping` triggers GitHub's webhook ping to verify delivery end to end.
+
+## Auth
+
+Token resolution order: `GITHUB_TOKEN` → `GH_TOKEN` → `gh auth token`
+(subprocess, if gh CLI is installed). No token storage by the tool.
+Required: classic PAT with `repo` (or `admin:repo_hook`) scope, or
+fine-grained PAT with repository **Webhooks: write** + **Metadata: read**.
+
+## Config
+
+JSON at `%APPDATA%\gh2discord\config.json` (Windows) or
+`$XDG_CONFIG_HOME/gh2discord/config.json` → `~/.config/gh2discord/config.json`
+(POSIX, written with mode 0600 — Discord webhook URLs are secrets).
+
+```json
+{
+  "version": 1,
+  "default_channel": "general",
+  "channels": { "general": "https://discord.com/api/webhooks/123/abc" },
+  "repos": { "owner/repo": { "channel": "general", "hook_id": 42, "events": ["*"] } }
+}
+```
+
+Channel URLs are stored canonically **without** the `/github` suffix (accepted
+and stripped on input); the suffix is appended when creating GitHub hooks.
+GitHub is the source of truth for hook state; `repos` is a local record that
+`status`/`untrack` reconcile against live data.
+
+Per-repo channels already work in v0.1: register additional channels with
+`channel add`, then `track --channel <name>`. No Discord bot required.
+
+## Modules (SRP)
+
+- `config.py` — load/save/validate config, path resolution. No network.
+- `github.py` — token resolution + thin GitHub REST client (urllib), hooks
+  CRUD, pagination. No config knowledge.
+- `commands.py` — business logic (track/untrack/status/ping/channel ops)
+  composing config + github. Returns structured results.
+- `cli.py` — argparse, dispatch, human-readable output, exit codes.
+
+Zero runtime dependencies (stdlib only). Python ≥ 3.9. Tests: pytest with a
+fake transport injected into the client (no network in unit tests).
+
+## Error UX
+
+- 401 → GitHub's message plus a token hint (set GITHUB_TOKEN/GH_TOKEN or
+  `gh auth login`).
+- 404 on hooks endpoints → "repo not found **or** token lacks admin/webhook
+  access" (GitHub returns 404, not 403, for missing hook permissions).
+- 3xx → repository renamed/transferred; redirects are never silently followed.
+- 422 → invalid event name(s), echo GitHub's message.
+- Console output degrades to `?` instead of crashing on legacy Windows code
+  pages (`reconfigure(errors="replace")`).
+- Missing token / missing default channel → actionable one-line fix.
+
+Exit codes: 0 ok, 1 API/config error, 2 usage error (argparse default).
+
+## Packaging
+
+`pyproject.toml` (hatchling), console script `gh2discord`, MIT license,
+English README. Install: `pipx install gh2discord` / `pip install gh2discord`.
+
+## Roadmap (post-v0.1)
+
+- `--bot` mode: create Discord channel + webhook automatically (bot token,
+  Manage Webhooks permission).
+- Polling mode for non-admin repos (releases.atom / Events API).
+- Org-wide webhook helper for organization accounts.

gh2discord-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gh2discord"
+version = "0.1.0"
+description = "One-command GitHub to Discord notifications: manage repo webhooks that post straight to your Discord channels."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Ozan Eski" }]
+keywords = ["github", "discord", "webhook", "notifications", "cli"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Version Control :: Git",
+  "Topic :: Communications :: Chat",
+]
+
+[project.urls]
+Homepage = "https://github.com/ozaneski13/gh2discord"
+Issues = "https://github.com/ozaneski13/gh2discord/issues"
+
+[project.scripts]
+gh2discord = "gh2discord.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gh2discord"]

gh2discord-0.1.0/src/gh2discord/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

gh2discord-0.1.0/src/gh2discord/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

gh2discord-0.1.0/src/gh2discord/cli.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__, commands
+from .config import ConfigError, load, normalize_repo, save
+from .github import AuthError, GitHubClient, GitHubError, resolve_token
+
+
+def _mask(url: str) -> str:
+    marker = "/api/webhooks/"
+    idx = url.find(marker)
+    if idx == -1:
+        return url
+    prefix = url[: idx + len(marker)]
+    parts = url[idx + len(marker):].split("/")
+    if len(parts) >= 2:
+        parts[1] = "***"
+    return prefix + "/".join(parts)
+
+
+def _client() -> GitHubClient:
+    return GitHubClient(resolve_token())
+
+
+def _cmd_channel_add(args) -> int:
+    cfg = load()
+    is_default = commands.channel_add(cfg, args.name, args.url, args.default)
+    save(cfg)
+    suffix = " (default)" if is_default else ""
+    print(f"channel '{args.name}' saved{suffix}")
+    return 0
+
+
+def _cmd_channel_list(args) -> int:
+    cfg = load()
+    if not cfg["channels"]:
+        print("no channels configured; add one with: gh2discord channel add <name> <url>")
+        return 0
+    for name in sorted(cfg["channels"]):
+        marker = "*" if name == cfg.get("default_channel") else " "
+        print(f"{marker} {name}  {_mask(cfg['channels'][name])}")
+    return 0
+
+
+def _cmd_channel_remove(args) -> int:
+    cfg = load()
+    commands.channel_remove(cfg, args.name)
+    save(cfg)
+    print(f"channel '{args.name}' removed")
+    return 0
+
+
+def _cmd_channel_default(args) -> int:
+    cfg = load()
+    commands.channel_default(cfg, args.name)
+    save(cfg)
+    print(f"default channel is now '{args.name}'")
+    return 0
+
+
+def _cmd_track(args) -> int:
+    cfg = load()
+    repo = normalize_repo(args.repo)
+    events = commands.parse_events(args.events)
+    result = commands.track(
+        _client(), cfg, repo, channel=args.channel, events=events, force=args.force
+    )
+    save(cfg)
+    print(
+        f"{result.action}: {result.repo} -> #{result.channel} "
+        f"(hook {result.hook_id}, events: {', '.join(result.events)})"
+    )
+    for warning in result.warnings:
+        print(warning, file=sys.stderr)
+    return 0
+
+
+def _cmd_untrack(args) -> int:
+    cfg = load()
+    repo = normalize_repo(args.repo)
+    deleted = commands.untrack(_client(), cfg, repo)
+    save(cfg)
+    if not deleted:
+        print(
+            f"no matching Discord hook found on {repo}; nothing deleted "
+            "(local record cleared)",
+            file=sys.stderr,
+        )
+        return 1
+    ids = ", ".join(str(i) for i in deleted)
+    print(f"untracked {repo} (deleted hook {ids})")
+    return 0
+
+
+def _cmd_list(args) -> int:
+    cfg = load()
+    if not cfg["repos"]:
+        print("no repos tracked; start with: gh2discord track <owner/repo>")
+        return 0
+    for repo in sorted(cfg["repos"]):
+        rec = cfg["repos"][repo]
+        events = ", ".join(rec.get("events", ["*"]))
+        print(f"{repo}  ->  #{rec.get('channel')}  (events: {events})")
+    return 0
+
+
+def _cmd_status(args) -> int:
+    cfg = load()
+    repo = normalize_repo(args.repo) if args.repo else None
+    if repo is None and not cfg["repos"]:
+        print("no repos tracked; start with: gh2discord track <owner/repo>")
+        return 0
+    rows = commands.status(_client(), cfg, repo)
+    failed = False
+    for row in rows:
+        if "error" in row:
+            failed = True
+            print(f"{row['repo']}: ERROR - {row['error']}")
+            continue
+        state = "active" if row["active"] else "DISABLED"
+        delivery = f"{row['code']} {row['status']}" if row["code"] else "no deliveries yet"
+        events = ", ".join(row["events"])
+        print(
+            f"{row['repo']}: {state}, hook {row['hook_id']} -> {_mask(row['url'])}, "
+            f"last delivery: {delivery}, events: {events}"
+        )
+    return 1 if failed else 0
+
+
+def _cmd_ping(args) -> int:
+    cfg = load()
+    repo = normalize_repo(args.repo)
+    hook_id = commands.ping(_client(), cfg, repo)
+    print(
+        f"ping sent to hook {hook_id} on {repo}; verify with 'gh2discord status {repo}' "
+        "or the repo's Settings -> Webhooks -> Recent Deliveries on GitHub"
+    )
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="gh2discord",
+        description="Wire GitHub repos to Discord channels with one command.",
+    )
+    parser.add_argument("--version", action="version", version=f"gh2discord {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    channel = sub.add_parser("channel", help="manage Discord channel webhooks")
+    channel_sub = channel.add_subparsers(dest="channel_command", required=True)
+
+    add = channel_sub.add_parser("add", help="register a Discord webhook under a name")
+    add.add_argument("name")
+    add.add_argument("url", help="Discord webhook URL (with or without /github suffix)")
+    add.add_argument("--default", action="store_true", help="make this the default channel")
+    add.set_defaults(func=_cmd_channel_add)
+
+    clist = channel_sub.add_parser("list", help="list registered channels")
+    clist.set_defaults(func=_cmd_channel_list)
+
+    remove = channel_sub.add_parser("remove", help="remove a registered channel")
+    remove.add_argument("name")
+    remove.set_defaults(func=_cmd_channel_remove)
+
+    default = channel_sub.add_parser("default", help="set the default channel")
+    default.add_argument("name")
+    default.set_defaults(func=_cmd_channel_default)
+
+    track = sub.add_parser("track", help="add/refresh the GitHub webhook for a repo")
+    track.add_argument("repo", help="owner/repo or GitHub URL")
+    track.add_argument("--channel", help="channel name (default: the default channel)")
+    track.add_argument(
+        "--events",
+        default="all",
+        help="comma-separated GitHub event list, or 'all' (default: all)",
+    )
+    track.add_argument(
+        "--force",
+        action="store_true",
+        help="retarget an existing Discord hook that points elsewhere",
+    )
+    track.set_defaults(func=_cmd_track)
+
+    untrack = sub.add_parser("untrack", help="delete the repo's Discord webhook")
+    untrack.add_argument("repo")
+    untrack.set_defaults(func=_cmd_untrack)
+
+    lst = sub.add_parser("list", help="list locally tracked repos")
+    lst.set_defaults(func=_cmd_list)
+
+    status = sub.add_parser("status", help="show live hook state and delivery health")
+    status.add_argument("repo", nargs="?", help="owner/repo (default: all tracked)")
+    status.set_defaults(func=_cmd_status)
+
+    ping = sub.add_parser("ping", help="send a GitHub ping through the hook")
+    ping.add_argument("repo")
+    ping.set_defaults(func=_cmd_ping)
+
+    return parser
+
+
+def main(argv: list | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(errors="replace")
+        except (AttributeError, ValueError):
+            pass
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except (ConfigError, AuthError, GitHubError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())