loco CLI: DCC Decoder Programming and Control Tool

Use the loco CLI to read and write CVs, program addresses, adjust volume and brightness, control functions, and reset decoders — all from a terminal.

The loco binary is a standalone command-line tool for working with DCC-equipped locomotives. You use it to read and write configuration variables (CVs), program decoder addresses, adjust sound volume and lighting brightness, map function keys to outputs, and send direct throttle commands — all from a terminal, without the BigFred web UI. Because loco writes to stdout and reads from stdin, it fits naturally into scripts and backup workflows.

Setup

Before running any loco command, create a configuration file at ~/.loco.yaml that tells the tool how to reach your command station.

The config file is read from ~/.loco.yaml or from a .loco.yaml in the current working directory, whichever is found first. CLI flags always take precedence over the file.

---

CV commands — loco prog cv

Configuration Variables (CVs) store all decoder settings — address, speed curves, motor control, lighting behaviour, and more. The loco prog cv command group lets you read and write them individually, in comma-separated lists, or as ranges.

Reading CVs

# Read a single CV — output is the bare value (e.g. "17")
loco prog cv get cv1

# Read multiple CVs by name
loco prog cv get cv1,cv2,cv5

# Read a contiguous range
loco prog cv get cv1-cv10

# Read with a default fallback value when the CV is unreadable
loco prog cv get cv52-53=0,cv1,cv5

By default, loco uses the programming track when no locomotive address is given. To read CVs from a locomotive sitting on the main track (Programming on Main, PoM), pass -t pom and supply the DCC address with -l:

# PoM read — locomotive must be on the main track, address 17
loco prog cv get cv2 -t pom -l 17

PoM reads are not acknowledged by all decoders. If cv get returns ERROR on the main track, fall back to the programming track.

Writing CVs

# Write a single CV
loco prog cv set cv29=5

# Write multiple CVs in one command
loco prog cv set cv1=17,cv29=5

# Write and read back to verify the result
loco prog cv set cv29=5 --verify

The --settle flag (default 300 ms) controls the pause between consecutive writes. Increase it if your decoder needs more recovery time between programming operations.

Bit-level writes — cv set-bit

When you only need to flip one or two bits inside a CV without disturbing the rest, use set-bit. Each assignment is CVnbn=<0|1> where b0 is the least significant bit.

# Set bit 5 of CV29 (enable long address) without touching other bits
loco prog cv set-bit cv29b5=1

# Clear bit 2 and set bit 5 in one pass
loco prog cv set-bit cv29b5=1,cv29b2=0

# Apply on the main track for loco 3
loco prog cv set-bit cv29b5=1 -l 3

Backup and restore

Because loco prints results to stdout and accepts input from stdin, you can build complete backup and restore workflows with standard shell tools.

# Back up CVs 1 through 10 to a file
loco prog cv get cv1-cv10 > backup.txt

# Restore those CVs from the backup file
cat backup.txt | loco prog cv set -- -

You can also maintain a hand-curated list of CVs to snapshot:

# cv-list.txt contains one CV or range per line, e.g.:
#   cv1
#   cv2
#   cv3-cv4
cat cv-list.txt | loco prog cv get -- -

Keep a backup file before experimenting with sound or motor tuning settings. If results are unsatisfactory, restore the original values with a single cat backup.txt | loco prog cv set -- - command.

CV verbosity and timeouts

All cv subcommands accept -v / --debug to print raw packet bytes to stderr (useful for diagnosing command station communication issues):

loco prog cv get -v cv1,cv5

You can also raise or lower the response timeout:

# Wait up to 30 seconds per CV (useful over a slow serial link)
loco prog cv get cv1-cv10 --timeout 30

--timeout 0 means zero seconds, not “no timeout”. Every command will fail immediately with no response or unrecognized response. Always use a value of at least 1.

---

Function commands — loco drive fn

The loco drive fn command group controls DCC functions (F0–F28) on a locomotive that is already running on the main track. Function state is managed through the command station.

Listing active functions

# Show all functions that are currently ON for loco 3
loco drive fn list -l 3

Example output when two functions are active:

F0 = On
F5 = On

Turning functions on and off

# Turn F0 on (lights on)
loco drive fn set 0 -l 3

# Turn F5 on (sound effect)
loco drive fn set 5 -l 3

# Turn F5 off
loco drive fn set 5 -l 3 --off

---

Drive commands — loco drive speed

The loco drive speed command sets or reads the speed and direction of a locomotive on the main track.

# Read current speed and direction
loco drive speed get -l 3

# Set speed to 50 (128-step mode), moving forward
loco drive speed set 50 -l 3 --forward

# Stop the locomotive
loco drive speed set 0 -l 3

# Emergency stop (speed step 1)
loco drive speed set 1 -l 3

# Use 28-step mode
loco drive speed set 20 -l 5 --steps 28

Speed values depend on the speed-step mode in use:

Steps	Range	Notes
14	0–15	0 = stop, 1 = emergency stop, 2–15 = steps 1–14
28	0–28	0 = stop, 1 = emergency stop, 2–28 = steps 1–27
128	0–127	0 = stop, 1 = emergency stop, 2–127 = steps 1–126

--loco is required for speed set and speed get. The command will refuse to run without it.

---

Programming commands — loco prog

The loco prog command group provides higher-level decoder operations that work on top of CV reads and writes: address programming, decoder detection, volume, brightness, function mapping, and factory reset.

All prog subcommands default to the programming track (when -l 0 or no -l flag). Passing a non-zero loco address with -l switches to PoM.

Decoder detection

Identify the decoder fitted to a locomotive by reading CV7 (version) and CV8 (manufacturer):

loco prog detect-decoder

Address programming

# Read the current address (reads CV1, CV17, CV18, and CV29)
loco prog addr get

# Program a long address (128–9999)
loco prog addr set 1234

# Program and verify the written values
loco prog addr set 1234 --verify

Volume — sound decoders only

# Read master volume as a percentage (0–100)
loco prog volume get

# Set master volume to 50%
loco prog volume set 50

The volume commands have no effect on decoders that do not support sound. detect-decoder can help confirm whether your decoder is a sound variant.

Brightness — per-output lighting levels

# List brightness for all addressable lighting outputs
loco prog brightness list

# Set O1 to 50% and O2 to 10% in one command
loco prog brightness set O1=50,O2=10

# Set multiple outputs with space-separated assignments
loco prog brightness set O1=10 O6=50

# Read the current brightness for output 1 (pass the output number)
loco prog brightness get 1

Identifying which output controls which light — brightness test

Before you can set meaningful brightness levels, you need to know which physical light on the model corresponds to each decoder output. The interactive test command lights one output at a time while you watch the model and press Enter to advance.

# Start the interactive identification sequence (5-second lead-in by default)
loco prog brightness test

Turn on all lighting functions on the vehicle before the test starts. The tool will:

1. Turn all outputs off.
2. Light each output in turn at 50% brightness (configurable with --brightness).
3. Pause and wait for you to press Enter after noting which light is on.
4. Restore all original brightness values when done.

Use the output numbers reported by the test when running loco prog mapping set.

Function mapping

Map DCC function keys to physical decoder outputs. Each assignment is FUNCTION=OUTPUTS; multiple outputs for the same function are comma-separated.

# Map F0 to outputs O1 and O2, F1 to O4 and O6
loco prog mapping set F0=O1,O2 F1=O4,O6

# Map F0 forward headlight only
loco prog mapping set F0=F0_F --forward

# Map F0 reverse headlight only
loco prog mapping set F0=F0_R --reverse

# Map F2 to AUX outputs, PoM on loco 3
loco prog mapping set F2=AUX3,AUX5 -l 3

Supported output tokens: O<n>, FO<n>, AUX<n>, F0_F (F0 forward), F0_R (F0 reverse). On RailBOX RB 2112/2110, use F0_F and F0_R instead of O1 for the headlight outputs.

Factory reset

Reset the decoder back to factory defaults by writing to CV8. The exact reset value is decoder-specific (RailBOX RB23xx: 1; ESU LokSound 5 and ZIMO MS/MN: 8). BigFred detects the decoder type automatically.

# Full factory reset
loco prog factory-reset

# Reset but restore the existing DCC address afterwards
loco prog factory-reset --preserve-addr

A factory reset overwrites all CV values, including any motor tuning, sound configuration, and function mappings you have set. Back up your CVs first with loco prog cv get cv1-cv255 > backup.txt.

---

Common flags

These flags are accepted by most loco subcommands:

Flag	Short	Default	Description
--debug	-v	false	Verbose output: prints raw packet bytes to stderr
--loco	-l	0	Locomotive DCC address. 0 = programming track; non-zero = PoM on main
--timeout		10	Command station response timeout in seconds
--track	-t	(auto)	Force track type: prog for programming track, pom for main track
--verify		false	Read back after writing to confirm the value was accepted
--retry		0	Retry the read request this many additional times on failure

When --loco is 0 and --track is not set, loco automatically selects the programming track. When --loco is a non-zero address and --track is not set, it automatically selects PoM. You can override this with an explicit --track flag.