# Script Hooks

Hooks let you run an arbitrary script or binary when a USB event fires. They are configured in `config.toml` as a list of `[[hooks]]` entries.

---

## Hook fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `device` | string | `"*"` | VID:PID to match, or `"*"` for any device |
| `event` | string | `"connected"` | `"connected"`, `"disconnected"`, or `"triggered"` |
| `script` | string | — | Absolute path to the script or binary |
| `enabled` | bool | `true` | Set to `false` to disable without deleting the entry |

---

## Events

| Event | When it fires |
|-------|---------------|
| `connected` | A USB device is plugged in |
| `disconnected` | A USB device is removed |
| `triggered` | The kill-switch fires (key device removed while armed) |

The `device` filter is matched against the VID:PID string (e.g. `"046D:C52B"`). Use `"*"` to match any device.

For the `triggered` event, the `device` field is ignored — the trigger always fires for the mapped key device.

---

## Examples

### Lock the screen when any device is disconnected

```toml
[[hooks]]
device  = "*"
event   = "disconnected"
script  = "/usr/bin/loginctl"
enabled = true
```

> The script is executed with no arguments. Wrap complex commands in a shell script.

### Run a custom script when the specific key device connects

```toml
[[hooks]]
device  = "046D:C52B"
event   = "connected"
script  = "/home/user/.local/bin/notify-key-present.sh"
enabled = true
```

### Send a notification when the kill-switch triggers

```toml
[[hooks]]
device  = "*"
event   = "triggered"
script  = "/home/user/.local/bin/alert.sh"
enabled = true
```

---

## Script arguments

Scripts receive three positional arguments:

```
<script> <VID:PID> <device-name> <event-type>
```

| Argument | Example | Description |
|----------|---------|-------------|
| `$1` | `1532:0A24` | VID:PID of the device |
| `$2` | `Razer Keyboard` | Human-readable device name (may be empty) |
| `$3` | `connected` | `connected`, `disconnected`, or `triggered` |

Example script:

```sh
#!/bin/sh
# /usr/local/bin/usb-hook.sh
VID_PID="$1"
NAME="$2"
EVENT="$3"
notify-send "USB $EVENT" "$NAME ($VID_PID)"
```

## Script environment

Scripts are executed directly (no shell wrapper). The script must be executable (`chmod +x`).

Scripts run asynchronously and their output is discarded. Failures are silently ignored — the shutdown sequence does not wait for hook scripts to complete.

---

## Adding hooks

Hooks can only be added by editing the config file directly — there is no GUI editor yet (planned). The app reloads the config on next start.

```toml
[[hooks]]
device  = "*"
event   = "connected"
script  = "/path/to/your/script"
enabled = true

[[hooks]]
device  = "046D:C52B"
event   = "disconnected"
script  = "/path/to/another/script"
enabled = false
```