This reference follows CLI 0.1.0 source, using gclight==0.1.0. Follow the quick start to download a standalone executable or run from source with uv. Here, gcli is shorthand: replace it with the downloaded executable's platform-specific path, or with uv run gcli for a source checkout.
Command structure and shared options
gcli --version
gcli version
gcli --help
gcli mini --help
gcli mini status --help
Both --version and version print CLI and SDK version text. Running gcli or gcli mini without a subcommand prints help and returns 0. mini bluetooth requires get, enable, or disable.
Connection options belong to the mini parser and must appear after mini but before the operation. info, state, status, control, and event commands require an explicit port; discover instead takes candidate ports as positional arguments after its subcommand:
| Option | Default | Constraint |
|---|---|---|
-p PORT, --port PORT | None; required except for discover | Explicit serial port, such as COM3, /dev/ttyACM0, or /dev/cu.usbmodem1101. |
--baudrate N | 115200 | Positive integer. |
--command-timeout SECONDS | 2.0 | Positive finite seconds for device commands, not an overall process deadline. |
The correct structure is gcli mini -p COM3 --command-timeout 3 state. The old structure gcli mini state --port COM3 is no longer accepted and exits with a parsing error. Operation-specific arguments still follow the operation, such as status fields or laser-on --current-ma. Each operation opens its own serial session and closes it when finished; separate CLI invocations do not share a persistent connection.
Discovery and read-only queries
| Command | Behavior and output |
|---|---|
mini [--baudrate N] [--command-timeout SECONDS] discover PORT [PORT ...] | Requires at least one candidate and does not require -p/--port. Returns a devices array with port, serial_number, and software_version entries. |
mini -p PORT info | Returns protocol_version, serial_number, and software_version. |
mini -p PORT state | Queries and returns timestamp_ms, output_enabled, actual_current_ma, and source. |
mini -p PORT status [FIELD ...] | Queries selected fields; omission queries all seven below. Fields must be unique. Returns timestamp_ms, values, and raw_fields. |
mini -p PORT bluetooth get | Returns {"enabled": true} or {"enabled": false} over serial, without establishing Bluetooth transport. |
gcli mini discover COM3 COM4
gcli mini -p COM3 info
gcli mini -p COM3 state
gcli mini -p COM3 status actual-current actual-voltage temperature-1
gcli mini -p COM3 bluetooth get
discover only probes supplied candidates and probes duplicate names once. Candidates that cannot be opened or identified are skipped, and probe connections are closed. Consequently, {"devices":[]} can still return exit code 0; it does not prove that no devices exist or that port permissions are correct.
status fields
Command-line names use hyphens; JSON keys under values use underscores. For example, actual-current maps to actual_current.
| CLI field | JSON key | Meaning |
|---|---|---|
output-state | output_state | Output switch, boolean |
actual-current | actual_current | Actual current, mA |
actual-voltage | actual_voltage | Actual voltage, mV |
temperature-1 | temperature_1 | Temperature, °C |
pd-data | pd_data | PD value scaled by the device profile; no assumed optical-power unit |
current-setting | current_setting | Current setting, mA |
bluetooth-state | bluetooth_state | Bluetooth switch, boolean |
Control commands
| Command | Behavior |
|---|---|
mini -p PORT laser-on --current-ma VALUE | Requires a current; sets current before requesting output enable in the same frame. |
mini -p PORT laser-off | Explicitly requests output disable. |
mini -p PORT set-current --current-ma VALUE | Sets current without changing the output switch. |
mini -p PORT bluetooth enable | Enables the device Bluetooth switch over serial; does not establish Bluetooth transport. |
mini -p PORT bluetooth disable | Disables the device Bluetooth switch over serial. |
--current-ma must be finite and non-negative. The SDK additionally enforces at most two decimal places and the identified device profile's current limits. Passing argument parsing does not guarantee device acceptance.
# Only after safety checks: the first command can cause real laser emission.
gcli mini -p COM3 laser-on --current-ma 120.00
# Explicit laser-off: the previous process exiting did not establish this.
gcli mini -p COM3 laser-off
gcli mini -p COM3 state
These are independent commands, not a fail-safe sequence. Timeouts, process interruption, or cable faults can prevent subsequent laser-off. Maintain an independent hardware shutdown method and confirm actual output is safe. Do not unconditionally retry a failed laser-on.
Successful control returns top-level success and receipt, with timestamp_ms and outcomes in the receipt. Device rejection is a runtime error, not a successful invocation returning only success:false.
Device events: set a count and timeout
gcli mini -p COM3 events --count 3 --event-timeout 2
| Option | Default | Meaning |
|---|---|---|
--count N | 1 | Positive integer; finish after collecting N events. |
--event-timeout SECONDS | None: unlimited wait | Per-event deadline in finite non-negative seconds; 0 does not wait. |
This command does not poll, turn the laser on, or start telemetry. It may time out if the device sends no reports. Without --event-timeout, even a finite --count can wait forever. Each wait has its own deadline; the example does not impose a single two-second limit on the entire invocation.
The command prints one {"events":[...],"stats":{...}} object only after collecting all events; it is not a JSON Lines stream. If any wait fails, the command exits with 1 and does not print partially collected events.
Events can contain telemetry (such as current_ma and pd_data, with nullable fields), state (output_enabled), or exception reports (error_bits). Each event has timestamp_ms and raw_fields; the JSON has no separate event-type field. stats contains dropped_telemetry_count and coalesced_state_count. The SDK event queue has a fixed capacity. If the application reads more slowly than the device reports, telemetry can be dropped and state reports can be combined, so events does not guarantee every device report. If the queue is full and cannot store an exception report, the SDK can close the connection and return an error.
stdout, stderr, and exit codes
- Successful device operation: one compact JSON object on stdout, followed by a newline. No
--jsonflag is needed or available. Do not rely on field order. - Version and help: plain text on stdout, not JSON.
- Runtime errors:
gcli: error: ...text on stderr, not JSON. This includes SDK, operating-system, and runtime argument-value errors. - Parsing errors: missing arguments, unknown commands, and invalid field names produce usage and error text on stderr.
| Exit code | Meaning |
|---|---|
0 | Success, including version, help, and discovery with no matches. |
1 | Handled runtime error, such as a port failure, device rejection, command/event timeout, duplicate status fields, or SDK current-range validation failure. |
2 | Argument parsing failure, such as missing -p/--port, placing connection options after the operation, invalid --count, or an unknown field name. |
Scripts must check the exit code before parsing stdout. Do not merge stderr into stdout and then parse the combined stream as JSON. Unhandled exceptions or external signals may terminate differently. Use $LASTEXITCODE in PowerShell or $? in POSIX shells.
When it is unclear whether the device executed a command, establish hardware safety first, then query state in a new invocation. The CLI does not automatically resend controls. For detailed error handling, a persistent connection, or per-event-type processing, use the Python SDK API.