Command-Line Interface

SyeLink provides a CLI for common tasks. All commands are available via syelink or uv run syelink.

Commands

Command

Description

syelink convert <asc_file>

Convert ASC file to JSON, text files, and/or CSV samples

syelink info <data_file>

Show session information (accepts ASC or JSON)

syelink export-samples <data_file>

Export gaze samples to CSV

syelink plot-validation <json_file>

Plot validation data

syelink plot-calibration <json_file>

Plot calibration data

convert

Convert an ASC file to structured output formats.

syelink convert data.asc            # Export all formats
syelink convert data.asc --json     # JSON only
syelink convert data.asc --text     # Text files only
syelink convert data.asc --samples  # CSV samples only

# Merge HREF coordinates from a matching `edf2asc -sh` export:
syelink convert data_gaze.asc --href data_href.asc

Options:

  • -o, --output – Output directory (default: same directory as ASC file)

  • --json – Export JSON file only

  • --text – Export text files only

  • --samples – Export gaze samples CSV only

  • --href – Path to a matching edf2asc -sh HREF ASC; merges per-sample HREF coordinates into the gaze samples and exports them alongside in the JSON and CSV

  • Without flags: exports all formats (JSON + text + CSV)

info

Show session information.

syelink info data.json
syelink info data.asc
syelink info data_gaze.asc --href data_href.asc

Shows calibration/validation counts, display info, and gaze sample statistics (including how many samples carry HREF coordinates when --href is used).

Options:

  • --href – Path to a matching edf2asc -sh HREF ASC (only valid when the input is an ASC; JSON inputs already carry HREF if it was merged at parse time)

export-samples

Export gaze samples to CSV.

syelink export-samples data.asc -o samples.csv
syelink export-samples data_gaze.asc --href data_href.asc -o samples.csv

Options:

  • -o, --output – Output CSV file path (default: <filename>_samples.csv)

  • --href – Path to a matching edf2asc -sh HREF ASC (only valid when the input is an ASC)

plot-validation

Generate a validation plot.

syelink plot-validation data.json -i 0 -o validation.png

Options:

  • -i, --index – Validation index (default: 0)

  • -o, --output – Output image path

  • --show – Show plot interactively

  • --target-image – Custom target image

plot-calibration

Generate a calibration plot.

syelink plot-calibration data.json -i 0 -o calibration.png

Options:

  • -i, --index – Calibration index (default: 0)

  • -o, --output – Output image path

  • --show – Show plot interactively