added initial script and readme

2026-05-15 07:20:52 -05:00
commit 62252a6abf
3 changed files with 143 additions and 0 deletions
@@ -0,0 +1,85 @@
+# applog
+
+A shell script that wraps `idevicesyslog` to show clean, colorized log output for a specific iOS app. Cuts through the noise of the full system log and surfaces only lines relevant to your app or bundle ID.
+
+## Requirements
+
+### macOS
+
+```sh
+brew install usbmuxd libimobiledevice
+```
+
+| Package | Role |
+|---------|------|
+| `usbmuxd` | USB multiplexer daemon — manages the connection between the host and iOS devices over USB |
+| `libimobiledevice` | Provides `idevicesyslog` and other iOS communication tools |
+
+> On macOS, Apple ships its own `usbmuxd` as part of the OS. If `idevicesyslog` works without the brew version, you can skip `usbmuxd`.
+
+### Linux
+
+```sh
+# Debian/Ubuntu
+sudo apt install usbmuxd libimobiledevice-utils
+
+# Arch
+sudo pacman -S usbmuxd libimobiledevice
+```
+
+### iOS device setup
+
+1. **Trust the host machine** — connect the device, tap *Trust* on the prompt, and enter your passcode.
+2. **Enable Developer Mode** (iOS 16+) — Settings → Privacy & Security → Developer Mode. The device will reboot.
+3. **Pair the device** (if prompted):
+   ```sh
+   idevicepair pair
+   ```
+
+### Other
+
+- bash 3.2+
+- USB cable (wireless/Wi-Fi connections are not supported by `idevicesyslog`)
+
+## Usage
+
+```sh
+./applog.sh <bundle-id-prefix|process-name>
+```
+
+**Examples:**
+
+```sh
+./applog.sh com.mycompany.myapp
+./applog.sh MyApp
+```
+
+Press `Ctrl+C` to stop.
+
+## Output
+
+Each matched line is colorized by log level and separated by a visual rule:
+
+| Color  | Level |
+|--------|-------|
+| 🔴 Red    | `<Error>`, `<Fault>` |
+| 🟡 Yellow | `<Warning>` |
+| 🔵 Cyan   | `<Notice>` |
+| 🟢 Green  | `<Info>` |
+| Gray   | `<Debug>` |
+
+## How filtering works
+
+Lines are included if they contain the filter string anywhere — the app's own process logs, plus system services acting on its behalf (network, Bluetooth, etc.).
+
+A blocklist of known noisy system daemons (`runningboardd`, `tccd`, `launchd`, and others) is excluded even when they reference your bundle ID, since those lines reflect system bookkeeping rather than app behavior.
+
+To suppress additional processes, add them to `BLOCKLIST_RE` near the top of the script.
+
+## Installation
+
+```sh
+chmod +x applog.sh
+# optionally move somewhere on your PATH
+cp applog.sh /usr/local/bin/applog
+```