commit cbe3162404c3c44cf3bf516e7bc5000f74b9f96b
Author: Timmy <timmy@automodules.com>
Date:   Wed Jun 24 16:40:12 2026 +0800

    docs: add WhatCable CLI README
    
    Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7d78f62
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+# WhatCable CLI 文件
+
+查 USB-C 連接埠與線材實際能力的工具。版本 1.1.2。
+
+參考:<https://www.whatcable.uk/cli>
+
+## 安裝
+
+```sh
+brew install --cask darrylmorley/whatcable/whatcable   # 選單列 App + CLI
+brew install darrylmorley/whatcable/whatcable-cli       # 只裝 CLI
+```
+
+## 系統需求
+
+- macOS 14 (Sonoma) 以上
+- Apple Silicon（M1+),不支援 Intel Mac
+
+## 基本用法
+
+```sh
+whatcable            # 掃描所有 USB-C 埠,輸出白話摘要(充電狀態、線材規格、裝置資訊)
+```
+
+## 選項
+
+| 選項 | 說明 |
+|------|------|
+| `--watch` | 持續監看變化(Ctrl+C 結束) |
+| `--json` | 輸出 JSON,方便接 `jq` 寫腳本 |
+| `--raw` | 一併輸出底層 IOKit 屬性,用於除錯 |
+| `--report` | 印出線材報告(markdown + GitHub 回報 URL)後結束 |
+| `--desktop` | 以 Dock App 視窗開啟 WhatCable |
+| `--popover` | 以選單列 popover 模式開啟 |
+| `--tb-debug` | 傾印 IOThunderboltSwitch 樹(協助開發 Thunderbolt 功能用) |
+| `--version` | 印出版本後結束 |
+| `-h`, `--help` | 顯示說明 |
+
+### Pro 功能(需授權)
+
+| 選項 | 說明 |
+|------|------|
+| `--dashboard` | 全螢幕 TUI 儀表板:埠、電力、Thunderbolt |
+| `--monitor` | 監看即時電力遙測 |
+| `--monitor-json` | 即時電力遙測輸出為 newline-delimited JSON |
+| `--activate KEY` | 啟用 Pro 授權(KEY 格式 XXXX-XXXX-XXXX-XXXX) |
+| `--licence` | 顯示目前 Pro 授權狀態 |
+| `--deactivate` | 移除本機儲存的 Pro 授權 |
+| `--pro` | 顯示 Pro 功能並開啟購買頁 |
+
+### 雜項
+
+| 選項 | 說明 |
+|------|------|
+| `--silence-pro-hints` | 隱藏輸出結尾的 Pro 提示 |
+| `--show-pro-hints` | 重新顯示 Pro 提示 |
+| `--test-kit` | 執行診斷探測並回傳資料以協助改善 WhatCable |
+
+## 範例
+
+```sh
+whatcable --watch                    # 即時監看插拔
+whatcable --json | jq '.ports'       # 取出埠資訊
+whatcable --report                   # 產生線材回報
+```