Refine README

1 files changed, 107 insertions, 2 deletions

diff --git a/README.md b/README.md
index cfb67c9..c065e25 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,112 @@
 
 `kl` is a lightweight, command-line global keystroke monitoring and echoing tool for GNU/Linux systems.
 
-This tool is compiled directly to native binary with zero runtime dependencies. No Node.js, No Electron, No pyhton, **written in Pure C**.
+This tool is compiled directly to native binary with zero runtime dependencies. No Node.js, No Electron, No Python, **written in pure C**.
 
-## Features
+## Install
 
+You can install it with aur.
+
+```bash
+paru -S kl
+```
+
+or build from source
+
+```
+git clone https://github.com/yingyu5658/keyboard-listener.git
+cd keyboard-listener
+sudo make install
+```
+
+## Usage
+
+`kl` designs to interaction with low-level kernel input events directly via `/dev/input/eventx`. We need to find the keyboard event file.
+
+```bash
+λ ~/ ls /dev/input/by-path
+pci-0000:00:14.0-usb-0:1:1.0-event-mouse  pci-0000:00:14.0-usb-0:9:1.1-event
+pci-0000:00:14.0-usb-0:1:1.0-mouse        pci-0000:00:14.0-usb-0:9:1.1-event-kbd
+pci-0000:00:14.0-usb-0:9:1.0-event-kbd    platform-pcspkr-event-spkr
+```
+
+Find a file which includes word like "keyboard", "kbd" and so on. For the first time of running `kl`, it will create a config file: `~/.klrc`, here is an example: 
+
+
+```
+# kl config file (v0.0.1)
+#
+# Please see your README for details.
+#
+# This file was auto-generated because it was missing.
+
+device = /dev/input/by-path/pci-0000:00:14.0-usb-0:9:1.0-event-kbd
+
+time = true
+
+```
+
+then run `sudo kl`:
+
+```
+λ ~/ sudo kl
+Device: /dev/input/by-path/pci-0000:00:14.0-usb-0:9:1.0-event-kbd
+2026-05-17 21:54:22.210831: P
+2026-05-17 21:54:22.330827: R
+2026-05-17 21:54:22.602797: O
+2026-05-17 21:54:22.866822: G
+2026-05-17 21:54:22.954814: R
+2026-05-17 21:54:23.026817: A
+2026-05-17 21:54:23.146814: M
+2026-05-17 21:54:23.378821: M
+2026-05-17 21:54:23.546794: I
+2026-05-17 21:54:23.626831: N
+2026-05-17 21:54:23.802818: G
+2026-05-17 21:54:23.898808: <SPACE>
+2026-05-17 21:54:24.082826: I
+2026-05-17 21:54:24.554789: N
+2026-05-17 21:54:24.746833: <SPACE>
+2026-05-17 21:54:24.890809: P
+2026-05-17 21:54:25.066811: U
+2026-05-17 21:54:25.170807: R
+2026-05-17 21:54:25.210811: E
+2026-05-17 21:54:25.570792: <SPACE>
+2026-05-17 21:54:25.762816: C
+```
+
+You can also disable time echo with `time = false`:
+
+```
+λ ~/dev/key-catcher/ main* sudo kl    
+Device: /dev/input/by-path/pci-0000:00:14.0-usb-0:9:1.0-event-kbd
+L
+E
+S
+S
+<SPACE>
+I
+S
+<SPACE>
+M
+O
+R
+E
+.
+
+```
+
+---
+
+## SECURITY & PERMISSIONS
+
+Due to the security model of modern Linux distributions (especially on Wayland/systemd-logind), direct access to these device nodes from an unprivileged GUI session is blocked to prevent unauthorized key logging.
+
+If it can't work properly, add your user to `input` group, and reboot your computer.
+
+```bash
+sudo usermod -aG input $USER
+```
+
+## Report Bug
+
+Feel free to create an issue or a pull request :)