Command line tool

Command-line tool

torqa-cli finds and rides smart trainers without the app — handy for testing trainers and sensors.

Install

Download the torqa-cli archive for your system from Releases and unpack it. Between releases, use a successful CI run on main (sign in to download workflow artifacts):

System	Download	Notes
macOS	torqa-cli-macos-arm64.tar.gz	Unsigned: run xattr -d com.apple.quarantine torqa-cli, and allow your terminal Bluetooth access
Windows	torqa-cli-windows-x86_64.zip	Run .\torqa-cli.exe in PowerShell; Bluetooth must be on
Linux	torqa-cli-linux-<arch>.tar.gz	glibc 2.35+; the bluetooth service running, adapter on (bluetoothctl power on)

Find devices

./torqa-cli scan               # 5 s scan for trainers, sensors and shifters
./torqa-cli scan --seconds 10

Wake the trainer by pedalling and disconnect other apps (Zwift, Wahoo): only one app can control it. Heart-rate straps usually only show up while worn.

Ride

./torqa-cli ride                       # strongest trainer found
./torqa-cli ride --trainer kickr --hr  # trainer by name, plus a heart-rate strap
./torqa-cli ride --fake                # simulated trainer, no hardware

Readings print every second. Type a command and press Enter:

Command	Effect
g 5	Simulate a 5 % grade
p 200	Hold 200 W (ERG)
r 30	Resistance at 30 %
q	Quit (or Ctrl+C)

All ride options

Option	Meaning
--trainer kickr	Trainer by name (any part, any case)
--hr [name]	Also connect a heart-rate strap
--fake	Simulated trainer with a simulated heart rate
--fake-power 200, --fake-cadence 90	What the simulated rider pedals
--controller [name]	Also connect a shifter: a Shimano Di2 or a Zwift Click (original or v2)
--up-channel 1, --down-channel 2	The buttons that shift up and down: Di2 channels, or a Click's + (1) and − (2); a Click v2's Y, Z, A, B are 3–6, its arrows 7–10
--scan-seconds 5	How long to scan

Ride a route

./torqa-cli route my-ride.gpx                  # length, climbing, map
./torqa-cli ride --route my-ride.gpx --hr      # the trainer follows the gradient
./torqa-cli ride --route my-ride.gpx --fake --time-scale 50   # quick test ride

The route is prepared as in the app; map and terrain data are cached, so routes work offline afterwards. The ride is saved as a FIT file.

All route options

Option	Meaning
--difficulty 50	Share of the gradient you feel on the trainer
--descent coast|flat	Coast downhill, or ride descents like flat roads
--mass 83	Rider plus bike in kg
--output ride.fit	Where to save the ride
--offline	Use cached data only
--time-scale 50	Faster simulated time (with --fake)
--gears 50x14	Virtual gears on a single cog; u / d and Enter shift
--world	(route only) also build the 3D world and report its size

Ride a workout

./torqa-cli ride --power 200 --hr                         # hold 200 W
./torqa-cli ride --hr-zone 3 --hr --max-hr 190 --ftp 250  # hold heart-rate zone 3
./torqa-cli ride --workout my.zwo --ftp 250             # a structured workout

./torqa-cli workout builtins lists the built-in workouts. Other options: --hr-target 140, --min-power, --max-power and --workout file.zwo (ZWO, ERG, MRC or FIT).

Check virtual gears

./torqa-cli gear-check --trainer kickr --gears 50x14

Rides a flat road in virtual gears and shows each second whether the trainer brakes as the gear asks. u / d shift, a number jumps to that gear, g 4 sets a 4 % road, q quits.

To check a shifter without a trainer, let --fake stand in for it; the gear changes as you press the shifter's buttons, and each device prints its battery level (battery 80 %) when it connects and whenever it changes:

RUST_LOG=torqa_devices=debug ./torqa-cli gear-check --fake --controller "Zwift Click v2"

Reading the output

gear 24 5.50  sent +0.0 % Crr 0.0062 Cw 0.72 |  420 W  91 rpm  41.0 km/h | felt 3.57 (real 3.57) | expect 1114 W, ungeared 327 W | virtual 49.3 km/h = 4.29

Part	Meaning
gear 24 5.50	Virtual gear and its ratio
sent …	Gradient, rolling resistance and wind sent to the trainer
felt … (real …)	The ratio the trainer turns in; should match the real gear
expect … W	What the trainer should brake at
ungeared … W	What it would brake without the gear

If the power stays near ungeared, the trainer ignores rolling resistance and wind, so gears only work on gradients.

Check a video

./torqa-cli video my-ride.mp4

Tells you whether a video course keeps up on this computer.

Sample rides

./torqa-cli sample-rides --weeks 8

Fills the active rider's history with made-up rides, e.g. to try the Analysis tab. Delete them afterwards.

Set RUST_LOG=debug for protocol details. If the trainer drops out, the CLI reconnects by itself.