Skip to content

CLI reference

Fin edited this page Nov 14, 2026 · 4 revisions

CLI reference

All commands here are python3 tuxchange/sp_relay.py <command>. The wrappers in scripts/ call the same thing.

sp_relay.py {run,import,status,ctl,identity,selftest}

run: the daemon

sudo python3 tuxchange/sp_relay.py run --store relay_store --iface mon0 --channel 1,6,11
Flag Default What it does
--store relay_store Where messages are kept. Also the seed for this box's identity.
--iface mon0 The monitor interface. Do not pass the real card.
--channel 1,6,11 Channels to watch.
--window 180 Seconds to listen per pass. A console that fails an engagement stops for a minute or more, so a short window tears the pass down mid-retry.
--idle 2 Pause between passes.
--cooldown 43200 Seconds before the same console is engaged again, keyed on the peer's address. This is Tuxchange's own limit, separate from the console's filter. See The MAC filter.
--mac Override the fixed identity.
--rotate-every 0 Present a new address every N seconds (minimum 60, 0 = never). Changes only at a pass boundary; persisted across restarts.
--rotate-identity off A new address for every pass. No real console does this.
--exchange-gap 0 Minimum seconds between completed exchanges.
--max-iface-failures 3 Exit after this many passes in a row with an unusable interface, so systemd restarts and rebuilds it.
--keep-runs 50 How many per-pass logs to retain. 0 keeps all of them.
--start-paused off Come up idle; resume over the control socket.
--yy-rate 11.0 Transmit rate in Mbps for the bulk transfer.
--manifest-repeat, --repeat-type 1, 0xf2 Send an object type N times to a console that went silent. Part of silent-send recovery.
--no-silent-recovery off Turn off the synthesised 0xF2 nudge. Leave it on unless you are testing.
--pcap off Capture each pass to a file.
--verbose 1 Log detail level.
--control-user whoever ran sudo The one non-root user allowed to use the control socket. Empty means root only.
--settings-file none Where adapter and rotation choices are saved. The service sets this to /var/lib/tuxchange/relay.env.
--run-logs on Should a log be written to the store on every pass?

ctl: control running daemon

python3 tuxchange/sp_relay.py ctl status --store /var/lib/tuxchange

Use --store /var/lib/tuxchange for the service, or your own path for a foreground run. Only root and the user named by --control-user can connect.

Command What it does
status Counts, current state, whether it is enabled.
pause / resume / toggle Stop and start engaging without stopping the process.
stop Shut the daemon down.
store The whole store in one round trip: titles, messages, what is servable.
import --path P [--replace] Ingest a dump into the store while running.
seed [--replace] [--mii-name N] [--author-name N] [--greeting G] Author this box's own Mii Plaza message.
forget [--mac M] Drop what is remembered about one peer, or about all of them without --mac.
encounters Who has been met, and when.
denylist Blocked peers and active cooldowns.
block --mac M [--note "why"] / unblock --mac M Refuse a specific console.
cooldown --mac M --seconds N Set a peer's remaining cooldown.
log [--limit N] The recent run log.
rotate --seconds N [--now] Set the identity-rotation period, saved for restarts under the service; --now also takes a new address at the next pass boundary.
set_adapter --adapter NAME Save the wireless adapter to use from the next service restart.
title_remove --title 00020800 Drop a title from the store.
message_remove --title T --id I --box inbox|outbox Drop one message.
`set_logs --logs on/off Control logging to a file in the store
`set_store --new-store Set the store to a root-owned and only root-read-and-write directory
`export [DEST] [--store STORE] [--title TITLE]... [--raw] [--dry-run] [--no-backup] [--backup-dir DIR] [--force] Exports CEC Inbox data into a directory to be used in an emulator, console, etc.

identity

python3 tuxchange/sp_relay.py identity --store relay_store

Prints the address this store transmits from. It is derived from the store path, so it is stable across restarts and differs between stores.

import

python3 tuxchange/sp_relay.py import /path/to/dump --store relay_store [--replace]
sudo python3 tuxchange/sp_relay.py import --from-log relay_store/runs/relay_1700000000.log --store relay_store

Takes a save image, a mounted dump, or an emulator NAND directory. --from-log recovers messages a console sent out of a run log instead. --replace empties the outbox first, which is what you want when swapping in another console's data.

status

Prints the store, or the running daemon's state if there is one.

selftest

python3 tuxchange/sp_relay.py selftest

See Running the self-tests.

The wrapper scripts

Script What it does
sudo ./scripts/tuxchange [iface] [channels] [args...] Monitor up, daemon in the foreground, machine put back on exit. Extra arguments go to run.
sudo ./scripts/tuxchange-link <iface> [channel] One handshake by hand, with a capture and a log. For debugging. It stops NetworkManager while it runs and arms a forced reboot for the run length plus eight minutes, cancelled on a clean exit.
sudo ./scripts/tuxchange-probe [iface] [channels] Transmit discovery probes only. The first thing to try when nothing responds.
sudo ./scripts/sp_monitor.sh up|down Build or tear down the active-monitor interface.

scripts/tuxchange picks the first ath9k adapter if you leave the interface off. scripts/tuxchange-link needs an interface, and scripts/tuxchange-probe defaults to wlan0.

Clone this wiki locally