Quick start

Download the standalone program first

gcli is the GC-Light command-line entry point for terminal use and script automation. The standalone executables below do not require a separate Python installation. This page describes command behavior for CLI source version 0.1.0, which depends on gclight==0.1.0 (Alpha). Only Mini protocol v1 over a serial connection is currently implemented; this is not a promise of production support for every model or system.

Choose the matching operating system and architecture. The macOS build targets Apple Silicon / arm64, not Intel Macs. Standalone packaging does not remove serial-driver, access-permission, or hardware-compatibility requirements.

Run the downloaded file

Open a terminal in the download directory. Every port below is an example: replace it with the actual port assigned by your operating system. Close Studio or other programs using that port first.

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 requires the .\ prefix to run a program in the current directory. If Windows displays a source or reputation warning, verify that the file came from this site's official OSS link before proceeding; do not disable system protection.

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

Your port may be /dev/ttyACM0 or /dev/ttyUSB0; use the actual assigned name. On Ubuntu, serial access is commonly managed through dialout. Log in again after an administrator updates group membership. Do not routinely run the controller as root to work around permissions.

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 is only an example. If macOS blocks the file, verify its official source and follow the system's Privacy & Security guidance; do not disable Gatekeeper globally. Intel Macs cannot use this arm64 build, and source installation does not establish compatibility for that hardware combination.

Version output includes both CLI and SDK versions. --help should list the mini subcommand. If an older file only lists version, do not apply the control examples to it: download again from the links above or use the source workflow below.

Alternative: run from source with uv

Use the official source repository when you need a Python development environment or cannot use the standalone program. This requires Git, uv, and Python 3.10+. uv can manage the project interpreter and dependencies.

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

Replace the port on Linux/macOS. uv tool install gclight-cli==0.1.0 is not currently an available installation path: the CLI package has not been provided on PyPI. The workflow above installs using the repository lockfile. After upstream changes, consult the installed command's --help.

Next: discover devices and wait for events

The command reference uses gcli as shorthand for the entry point. For a standalone download, substitute its full launch name from above. For a source checkout, substitute uv run gcli. Connection options must appear between mini and the operation.

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 probes only the supplied candidate ports. It does not enumerate or scan all system ports.
• events waits for device events. It neither enables the laser nor polls the device. Set both an event count and a per-event timeout to prevent the command from waiting indefinitely.
• Successful device commands write one JSON object to stdout. Version and help output are text. Runtime errors go to stderr with a nonzero exit code.
• Bluetooth commands only query or change the device Bluetooth switch over serial; they do not provide Bluetooth transport.

A timeout or send failure can leave it unclear whether the device executed the command. Establish hardware safety, then query state after reconnecting before deciding what to do. Do not automatically retry laser-on. See command and error behavior, or use the Python SDK for a persistent connection or per-event-type handling.