Using the CLI

# Using the CLI

The `tonepush` command does everything the editor does, plus a few things only a command line makes convenient: bulk backups, scripted parameter changes, and protocol work.

Commands in this page without a namespace operate on Line 6 devices. The
StompStation PRO uses `tonepush pro …`; see the [StompStation PRO guide](/stompstation-pro/)
for its schema paths, 1-based slots, NAM/stereo-IR operations, and verified
rollback requirements.

## Everyday commands

```sh
tonepush list             # find attached devices
tonepush info             # identity and firmware
tonepush presets          # every preset by name
tonepush select 7         # load index 7, which the device labels 03B
tonepush chain            # the signal chain, named, with values
tonepush topology         # the chain as it is wired, one row per branch
tonepush set 4 Drive 5.0  # set a parameter by name, in displayed units
tonepush enable 4 off     # bypass a block
tonepush snapshot 2       # switch snapshot
tonepush move 4 5         # reorder blocks
tonepush save             # commit the edit buffer; without this, edits are lost
```

`save` writes to the loaded preset's own slot and setlist; name an index or pass `--setlist` to save somewhere else.

Preset indices are zero-based within a setlist: index 7 is `03B` on an HX Stomp, with three presets to a bank, and `02D` on an HX Effects, with four. Parameter values are typed in the units HX Edit displays (`5.0` on a knob shown 0..10, `100` on a percentage, `Limit` on a switch) and converted for you.

## Backups and files

```sh
tonepush backup tone.bin  # the loaded preset, byte for byte
tonepush restore tone.bin # and back again
tonepush backup-all dir/  # every preset in the setlist, one file each
tonepush export tone.json # human-readable export, for diffing
tonepush import a.hlx --dry-run   # preview an .hlx; needs no hardware
```

A backup is the device's own preset document, untouched. Restoring one puts back exactly what was there, including anything this editor does not model.

## Blocks, routing, settings

```sh
tonepush copy-block 1 3   # copy a block over another slot
tonepush copy-snapshot 1 2
tonepush route 0 "Return" # route an input or output
tonepush setting 203      # read a device setting; set-setting writes
tonepush rename 7 "New Name"
tonepush ir-load 1 cab.wav
```

## Footswitches and controllers

```sh
tonepush assign 4 --cc 20        # block 4's bypass follows MIDI CC 20
tonepush switch-assign 4 2       # footswitch 2 toggles block 4
tonepush assign-param 4 0 1      # block 4's first parameter follows EXP 1
tonepush assign-cc 4 0 21        # ...or MIDI CC 21, once it is under MIDI
tonepush assign-range 4 0 0.8 --max
tonepush assignments 4 6         # what controls block 4's first six parameters
```

Blocks are numbered from 1 everywhere, as `tonepush chain` prints them; `enable 4`, `assign 4` and `switch-assign 4 2` all mean the same block. Parameters are numbered from 0, in the device's own order. Earlier versions took a zero-based block for `switch-assign`, `assign-param`, `assign-cc`, `assign-range`, `assignment-raw` and `assignments`, so scripts written for them need their block numbers raised by one.

## Many commands at once

Every command opens its own USB session, and on some pedals that takes seconds. `batch` runs a file of commands, one per line, over a single session:

```sh
tonepush batch build.txt
tonepush batch < build.txt
```

```text
# A preset build. Quotes keep spaces in a value.
select 03B
model 2 "Scream 808"
set 2 Gain 0.4
snapshot 2
sleep 600
enable 2 off
```

The whole file is read first, so a typo stops it before the pedal is touched. A line that fails on the pedal is reported with its number and the rest still run, and the command then exits non-zero with how many failed. `sleep <ms>` waits: the pedal stores a snapshot's block states as you leave it, so allow about 600 ms either side of a snapshot switch. `watch`, `pro` and `batch` itself cannot run inside a batch.

## Watching and poking

```sh
tonepush watch            # stream front-panel activity
tonepush models           # browse the catalog; needs no hardware
tonepush decode capture.log   # decode a USB capture; needs no hardware
```

`watch` prints what the device reports as you touch the front panel, which is also the fastest way to discover what an unlabelled control actually sends. `decode` replays the captures the protocol documentation was reconstructed from; the [opcode dictionary](/opcodes/) is the map.

The tonepush command does everything the editor does, plus a few things only a command line makes convenient: bulk backups, scripted parameter changes, and protocol work.

Commands in this page without a namespace operate on Line 6 devices. The StompStation PRO uses tonepush pro …; see the StompStation PRO guide for its schema paths, 1-based slots, NAM/stereo-IR operations, and verified rollback requirements.

Everyday commands

tonepush list             # find attached devices
tonepush info             # identity and firmware
tonepush presets          # every preset by name
tonepush select 7         # load index 7, which the device labels 03B
tonepush chain            # the signal chain, named, with values
tonepush topology         # the chain as it is wired, one row per branch
tonepush set 4 Drive 5.0  # set a parameter by name, in displayed units
tonepush enable 4 off     # bypass a block
tonepush snapshot 2       # switch snapshot
tonepush move 4 5         # reorder blocks
tonepush save             # commit the edit buffer; without this, edits are lost

save writes to the loaded preset’s own slot and setlist; name an index or pass --setlist to save somewhere else.

Preset indices are zero-based within a setlist: index 7 is 03B on an HX Stomp, with three presets to a bank, and 02D on an HX Effects, with four. Parameter values are typed in the units HX Edit displays (5.0 on a knob shown 0..10, 100 on a percentage, Limit on a switch) and converted for you.

Backups and files

tonepush backup tone.bin  # the loaded preset, byte for byte
tonepush restore tone.bin # and back again
tonepush backup-all dir/  # every preset in the setlist, one file each
tonepush export tone.json # human-readable export, for diffing
tonepush import a.hlx --dry-run   # preview an .hlx; needs no hardware

A backup is the device’s own preset document, untouched. Restoring one puts back exactly what was there, including anything this editor does not model.

Blocks, routing, settings

tonepush copy-block 1 3   # copy a block over another slot
tonepush copy-snapshot 1 2
tonepush route 0 "Return" # route an input or output
tonepush setting 203      # read a device setting; set-setting writes
tonepush rename 7 "New Name"
tonepush ir-load 1 cab.wav

Footswitches and controllers

tonepush assign 4 --cc 20        # block 4's bypass follows MIDI CC 20
tonepush switch-assign 4 2       # footswitch 2 toggles block 4
tonepush assign-param 4 0 1      # block 4's first parameter follows EXP 1
tonepush assign-cc 4 0 21        # ...or MIDI CC 21, once it is under MIDI
tonepush assign-range 4 0 0.8 --max
tonepush assignments 4 6         # what controls block 4's first six parameters

Blocks are numbered from 1 everywhere, as tonepush chain prints them; enable 4, assign 4 and switch-assign 4 2 all mean the same block. Parameters are numbered from 0, in the device’s own order. Earlier versions took a zero-based block for switch-assign, assign-param, assign-cc, assign-range, assignment-raw and assignments, so scripts written for them need their block numbers raised by one.

Many commands at once

Every command opens its own USB session, and on some pedals that takes seconds. batch runs a file of commands, one per line, over a single session:

tonepush batch build.txt
tonepush batch < build.txt

# A preset build. Quotes keep spaces in a value.
select 03B
model 2 "Scream 808"
set 2 Gain 0.4
snapshot 2
sleep 600
enable 2 off

The whole file is read first, so a typo stops it before the pedal is touched. A line that fails on the pedal is reported with its number and the rest still run, and the command then exits non-zero with how many failed. sleep <ms> waits: the pedal stores a snapshot’s block states as you leave it, so allow about 600 ms either side of a snapshot switch. watch, pro and batch itself cannot run inside a batch.

Watching and poking

tonepush watch            # stream front-panel activity
tonepush models           # browse the catalog; needs no hardware
tonepush decode capture.log   # decode a USB capture; needs no hardware

watch prints what the device reports as you touch the front panel, which is also the fastest way to discover what an unlabelled control actually sends. decode replays the captures the protocol documentation was reconstructed from; the opcode dictionary is the map.