Skip to content

CLI Reference

Jump to bottom
pq-cybarg edited this page May 29, 2026 · 1 revision

CLI Reference

The tetherand binary is the host-side reverse-tether driver. Once built (make build) it lives at bin/tetherand in the repo.

Commands

tetherand run

The main command. Starts the reverse-tether and blocks until you press Ctrl-C.

tetherand run                       # USB-ADB transport (default)
tetherand run --transport adb       # explicit USB-ADB
tetherand run --transport tcp       # LAN-TCP transport
tetherand run --transport bt        # Bluetooth-RFCOMM (M2)
tetherand run --transport aoa       # USB Open Accessory (M2)
tetherand run --device <SERIAL>     # target a specific adb device
tetherand run --port 31416          # override the default reverse port

The ADB transport works by running adb reverse localabstract:tetherand tcp:N to bridge the phone's LocalSocket back to a TCP port on the laptop. The relay binds that TCP port and forwards traffic through the host's normal network egress.

tetherand install

Installs bin/tetherand.apk on the connected device. Equivalent to adb install -r bin/tetherand.apk.

tetherand install                   # default device
tetherand install --device <SERIAL> # explicit

tetherand uninstall

Removes the dev.tetherand.app package from the device.

tetherand uninstall
tetherand uninstall --device <SERIAL>

tetherand status

Prints the connected devices list and the installed Tetherand version.

tetherand tui

Opens a four-panel terminal dashboard:

  • TRANSPORTS — which transports are connected.
  • TRAFFIC — sparkline of recent rx/tx volume.
  • DEVICES — connected adb devices.
  • EVENTS — recent connect/disconnect events.

Press q, Q, or Esc to exit.

Convenience wrappers

For users who haven't built the CLI binary yet, shell wrappers at the repo root provide a similar interface using upstream Gnirehtet:

./connect.sh                        # start tether (uses bin/tetherand if present,
                                    # else falls back to gnirehtet)
./connect.sh --stop                 # tear down
./connect.sh --reinstall            # uninstall + reinstall + relaunch

DEFCON pre-flight scripts

These ship in scripts/ and at the repo root for convenience:

./tutorial.sh                       # browser playbook on http://localhost:7331
./backup.sh                         # local encrypted backup of the phone
./restore.sh                        # restore from backup
./scripts/defcon-prep.sh            # pre-conference hardening
./scripts/defcon-prep.sh --post     # post-conference attestation diff

Build / release / verification scripts

./scripts/hash-artifacts.sh         # emit SHA-256 + SHA3-256 sidecars
./scripts/bundle-combinations.sh    # emit every native-lib subset zip
./scripts/release-sign.sh           # build + zipalign + apksigner-sign release APK
./scripts/release-upload.sh v0.1    # upload assets to a GitHub release
./scripts/smoke-device.sh           # on-device smoke walk
./scripts/install-launchagent.sh    # install macOS LaunchAgent

The LaunchAgent watches USB attach events for the Solana Seeker's vendor:product IDs (0x18d1:0x4ee7 / 0x4ee2 / 0x2d01 / 0x2d00) and auto-fires tetherand run whenever the device is plugged in.

Makefile targets

make build           # cargo build + apk build + hash sidecars
make native-all      # cross-compile all 5 native libs
make native-{wg,tor,nym,pt,rtlsdr} # individual native libs
make apk             # repackage APK with current jniLibs + emit hashes
make install         # adb install + pre-grant VPN consent
make smoke           # end-to-end test
make smoke-device    # on-device tab walk
make hashes          # regenerate sidecars
make release         # debug-signed release APK
make release-signed  # full release-signing pipeline
make launcher        # install macOS LaunchAgent
make test            # cargo test --workspace
make clean           # cargo + gradle clean + bin/ wipe

Environment variables

Variable Default What it does
NDK_HOME / ANDROID_NDK_HOME autodetected from ~/Library/Android/sdk/ndk/* Path to the Android NDK installation
ANDROID_HOME ~/Library/Android/sdk Path to the Android SDK (apksigner, zipalign)
CARGO_HOME ~/.cargo Used by remap-path-prefix scrubbing
KEYSTORE ~/.android/debug.keystore Signing keystore for release-signed
KS_PASS / KEY_PASS android (debug) Keystore + key passwords
KEY_ALIAS androiddebugkey Keystore alias
TETHERAND_SIGNING_ALLOW ~/.tetherand-signing-allow Approved-DN allow-list file
TETHERAND_NYM_SDK 0 Set to 1 to enable nym-sdk feature on the Nym build (requires a nightly toolchain)
TETHERAND_USB_POLL_SEC 1 LaunchAgent USB-watcher poll interval

Tetherand · GPLv3 · Source · Releases

Tetherand

Use

Features

Build

Project

Clone this wiki locally