优先下载独立程序
gcli 是 GC-Light 的命令行入口，适合终端操作与脚本自动化。以下独立可执行文件无需另装 Python。本文说明 CLI 源码版本 0.1.0 的命令行为，该版本依赖 gclight==0.1.0（Alpha）；当前只支持 通过串口使用 Mini 协议 v1，不代表所有型号或系统的生产级支持。
选择与电脑系统及架构匹配的文件。macOS 包面向 Apple Silicon / arm64，不是 Intel Mac 通用包。独立打包不免除 USB 串口驱动、系统访问权限及硬件兼容性要求。
启动下载的文件
在终端进入下载文件所在目录。命令中的端口均为示例，必须替换为系统实际分配的串口。开始前关闭占用该端口的 Studio 或其他程序。
Windows · PowerShell · x86_64
.\gcli-windows-x86_64.exe --version
.\gcli-windows-x86_64.exe --help
.\gcli-windows-x86_64.exe mini --help
.\gcli-windows-x86_64.exe mini -p COM3 info
.\gcli-windows-x86_64.exe mini -p COM3 state
PowerShell 运行当前目录程序需要 .\ 路径前缀。如果系统提示文件来源或信誉风险，先确认下载来自本站官方 OSS 链接，不要关闭系统防护。
Linux · x86_64
chmod +x ./gcli-linux-x86_64
./gcli-linux-x86_64 --version
./gcli-linux-x86_64 --help
./gcli-linux-x86_64 mini --help
./gcli-linux-x86_64 mini -p /dev/ttyACM0 info
./gcli-linux-x86_64 mini -p /dev/ttyACM0 state
串口名称可能为 /dev/ttyACM0 或 /dev/ttyUSB0，以本机实际结果为准。Ubuntu 串口权限通常由 dialout 组管理；管理员修改组成员后需重新登录。不要长期以 root 运行控制程序来绕过权限配置。
macOS · Apple Silicon
chmod +x ./gcli-macos-arm64
./gcli-macos-arm64 --version
./gcli-macos-arm64 --help
./gcli-macos-arm64 mini --help
./gcli-macos-arm64 mini -p /dev/cu.usbmodem1101 info
./gcli-macos-arm64 mini -p /dev/cu.usbmodem1101 state
/dev/cu.usbmodem1101 只是示例。若 macOS 阻止打开，核验官方来源后按系统“隐私与安全性”提示处理；不要全局关闭 Gatekeeper。若使用 Intel Mac，不能使用这个 arm64 包；源码安装也不代表该硬件组合已获兼容性验证。
版本输出同时包含 CLI 与 SDK 版本。--help 应显示 mini 子命令；若旧文件只有 version，不要继续套用控制示例，请重新从上方链接下载，或使用下面的源码方式。
uv 源码安装：备用方式
需要 Python 开发环境或独立程序不适用时，可从官方源码仓库运行。需要 Git、uv 与 Python 3.10+；uv 可管理项目解释器和依赖。
git clone https://github.com/Pidbid/gclight-cli.git
cd gclight-cli
uv sync --locked
uv run gcli --version
uv run gcli mini --help
uv run gcli mini -p COM3 info
Linux/macOS 请替换端口。当前不将 uv tool install gclight-cli==0.1.0 作为可用安装路径：CLI 包尚未在 PyPI 上提供。以上使用仓库锁文件安装；仓库更新后的命令以本地 --help 为准。
下一步：发现设备与等待事件
命令参考统一以 gcli 表示程序入口。使用独立文件时，将它替换为上文对应的完整启动名称；使用源码时替换为 uv run gcli。连接参数必须放在 mini 与具体子命令之间。
gcli mini discover COM3 COM4
gcli mini -p COM3 status actual-current temperature-1
gcli mini -p COM3 events --count 3 --event-timeout 2
discover只探测给出的候选端口，不会自动枚举或扫描系统全部串口。events等待设备事件，不会自动开光或轮询设备。请同时设置事件数量和每次等待超时，避免命令一直等待。- 成功的设备命令将一个 JSON 对象写入 stdout；版本与帮助是文本。运行错误写入 stderr，并返回非零退出码。
- 蓝牙命令只通过串口查询或切换设备蓝牙开关，不提供蓝牙连接传输。
若命令超时或发送失败，设备是否已经执行可能不确定。先确保硬件安全，下一次连接后查询状态，再决定是否操作；不要自动重试开光命令。详见命令与错误说明，需要长连接或按事件类型处理时使用 Python SDK。