CLI Reference

Common GhostESP CLI commands grouped by category.

Connecting to the CLI interface

  • Use a serial console (115200 baud is recommended) with a USB data cable or the built-in Terminal app on touch-enabled boards.
  • From the web UI, open the Terminal panel for remote access. When you launch a Wi-Fi or BLE command, the device suspends the GhostNet AP until the radio work finishes; once you run stop (or the command completes), BLE deinitializes and Wi-Fi returns automatically.
  • Send help to confirm connectivity; output appears prefixed with > in the console.

Core

  • help [category|all] — List commands by category (wifi, ble, portal, comm, sd, led, gps, misc, printer, cast, capture, beacon, attack).
  • chipinfo — Print SoC model, cores, features, and IDF version.
  • (for developers) mem [dump|trace <start|stop|dump>] — Print heap stats, dump allocation state, or control heap tracing.
  • reboot — Soft restart the device.
  • timezone <TZ> — Set timezone, e.g., timezone EST5EDT,M3.2.0,M11.1.0.
  • stop — Global kill switch: halt Wi-Fi attacks, BLE/BLE spam, GPS logging, wardriving, PCAP/CSV captures, RGB effects, and other background timers. It also tears down the BLE stack so suspended Wi-Fi/AP services come back online.

WiFi

Scanning

  • scanap [seconds|-live|-stop] — Run an AP scan, optionally for a set duration, live channel hop, or stop (-stop).
  • scansta — Hop channels and log associated stations.
  • scanall [seconds] — Combined AP and STA scan with summary.
  • sweep [-w wifi_sec] [-b ble_sec] — Full environment sweep: scans WiFi APs, stations, and BLE devices, then saves a CSV report to SD (/mnt/ghostesp/sweeps/sweep_N.csv).
  • list [-a|-s|-airtags] — Show AP scan results, associated stations, or AirTags.
  • listenprobes [channel|stop] — Monitor probe requests and log to PCAP if SD is present.

Targeting

  • select [-a|-s|-airtag] <idx[,idx]> — Queue APs, a station, or an AirTag by index for later actions.
  • connect <ssid> [pass] — Join an infrastructure network (saves credentials); wrap SSID/password in quotes when they contain spaces, e.g., connect "My SSID" "My Password".
  • disconnect — Leave the current STA connection.
  • apcred <ssid> <pass> or apcred -r — Change or reset GhostNet AP credentials.
  • apenable on|off — Toggle AP persistence across reboots.

Offense

  • attack -d|-e|-s <password> — Trigger deauth, EAPOL logoff, or SAE flood (-s needs ESP32-C5/C6 and the target PSK).
  • stopdeauth / stopspam — Halt active attacks or beacon floods.
  • beaconspam [mode] — Broadcast spoof SSIDs (-r, -rr, -l, or custom text).
  • karma start [ssid...] / karma stop — Respond to client probes with saved or provided SSIDs.
  • pineap [-s] — Monitor Pineapple-style beacons; -s stops detection.
  • saeflood <password> / stopsaeflood / saefloodhelp — Launch, stop, or review SAE flood attack guidance.

Network

  • scanports <local|ip> [all|start-end], scanarp, scanlocal, scanssh <ip> — Scan the subnet, a target host, or run mDNS/SSH discovery utilities.
  • dhcpstarve <start [threads]|stop|display> — Flood a DHCP server or show collected leases.
  • capture <-probe|-deauth|-beacon> — Start packet captures for the specified frame type to SD.

Output

  • powerprinter [ip text font alignment] — Send formatted PCL text jobs to LAN printers; pull saved defaults when arguments are omitted.
  • dialconnect — Pair with a DIAL-capable device (e.g., Chromecast/YouTube).

BLE

(ESP32-S2 excluded)

Discovery

  • blescan [-f|-ds|-a|-r|-s] — Scan for BLE devices, Flippers, spam detectors, or raw advertising; -s stops.
  • blewardriving [-s] — Log BLE beacons with GPS metadata.

Spoofing

  • blespam [mode|-s] — Emit spoofed BLE advertisements (Apple, Microsoft, Samsung, Google, random).
  • spoofairtag / stopspoof — Launch or stop AirTag spoofing.

Devices

  • listflippers — Scan for nearby Flipper Zero devices.
  • selectflipper <idx> — Choose a Flipper from the discovered list for interactions.
  • listairtags — Discover nearby AirTags.
  • selectairtag <idx> — Choose an AirTag for follow-up actions.

GATT

  • blescan -g — Scan for connectable BLE devices for GATT enumeration.
  • listgatt — List discovered GATT devices with tracker type detection.
  • selectgatt <idx> — Select a device by index for enumeration or tracking.
  • enumgatt — Connect to the selected device and enumerate its GATT services.
  • trackgatt — Track the selected device using real-time RSSI signal strength.

Portal

  • startportal <path|default> <AP_SSID> [PSK] — Serve an Evil Portal bundle from SD or flash (default uses the built-in portal).
  • stopportal — Shut down the active portal.
  • listportals — List bundles on SD card or flash.
  • evilportal -c <sethtmlstr|clear> — Manage the Evil Portal HTML buffer (-c sethtmlstr to capture inbound HTML, -c clear to revert to defaults).
  • webauth on|off — Require or disable web UI login.
  • commdiscovery — Enter UART discovery mode, broadcasting handshake frames until peers reply (run before commconnect).
  • commconnect <peer_name> — Connect to a discovered peer (after commdiscovery).
  • commsetpins <tx> <rx> — Save preferred pins.
  • commsend <command> [data...] — Issue commands to the connected peer.
  • commstatus — Inspect current link state.
  • commdisconnect — Close the peer link.

Storage

File Operations

  • sd status — Show SD card mount status, type (physical/virtual), capacity, and usage percentage.
  • sd list [path] — List files and directories with indices for quick reference. Default path: /mnt/ghostesp.
  • sd info <index|path> — Display file or directory details (type, size, path).
  • sd size <index|path> — Get file size in bytes (for pre-download checks).
  • sd read <index|path> [offset] [length] — Read file with optional offset and length for chunked downloads. No size limit.
  • sd write <path> <base64data> — Create/overwrite file with base64-decoded data.
  • sd append <path> <base64data> — Append base64-decoded data to file.
  • sd mkdir <path> — Create a new directory.
  • sd rm <index|path> — Delete a file or empty directory.
  • sd tree [path] [depth] — Recursive directory listing (default depth: 2, max: 10).

All sd commands return machine-parsable output with prefixes like SD:OK:, SD:ERR:, SD:FILE:[n], SD:DIR:[n]}, SD:READ:, SD:WRITE:.

Pin Configuration

  • sd_config — Display SD mode, pins, and status.
  • sd_pins_spi <cs> <clk> <miso> <mosi> — Configure SPI wiring.
  • sd_pins_mmc <clk> <cmd> <d0> <d1> <d2> <d3> — Configure SDIO wiring.
  • sd_save_config — Persist SD settings to storage.

RGB

  • rgbmode <rainbow|police|strobe|off|color> — Run an LED effect immediately.
  • setrgbmode <normal|rainbow|stealth> — Persist the LED mode across reboots.
  • setrgbpins <r> <g> <b> — Override discrete RGB GPIOs; pass the same pin for all three values to switch into single-wire NeoPixel mode on that data pin.
  • setrgbcount <1-512> — Persist the number of RGB LEDs connected so effects span the correct length. Reinitializes immediately if pins are already configured.
  • setneopixelbrightness <0-100> / getneopixelbrightness — Control NeoPixel intensity.

Status display (if present)

  • statusidle [list|set <life|ghost|0|1>] — View or change the status OLED idle animation when CONFIG_WITH_STATUS_DISPLAY and a status display are enabled.
    • statusidle — Show the current idle animation and timeout.
    • statusidle list — List available idle animations.
    • statusidle set <life|ghost|0|1> — Select the idle animation mode.

Infrared

  • ir list [path] — List .ir files (default: /mnt/ghostesp/infrared/remotes).
  • ir show <path|remote_index> — Parse and display signals from an IR file. After ir list, you can pass a numeric remote index.
  • ir send <path|remote_index> [button_index] — Transmit a signal from a file. Use remote_index from ir list and optional button_index from ir show.
  • ir universals list [-all] — List universal IR files and, with -all, all built‑in universal signals.
  • ir universals send <index> — Transmit a built‑in universal signal by index (see ir universals list -all).
  • ir universals sendall <file|TURNHISTVOFF> <button_name> [delay_ms] — Transmit all signals for a named button from a universal file or the built‑in TURNHISTVOFF set; can be stopped with stop.
  • ir rx [timeout] — Wait up to timeout seconds (default 60) for a single IR signal, print it (decoded or RAW), then stop.
  • ir learn [path] — Wait for a signal (10s). Without path, auto-create a new .ir file under /mnt/ghostesp/infrared/remotes; with path, append the learned signal to that file.
  • ir dazzler [stop] — Start/stop continuous IR dazzler flood. Responses are machine-parsable: IR_DAZZLER:STARTED, IR_DAZZLER:FAILED, IR_DAZZLER:ALREADY_RUNNING, IR_DAZZLER:STOPPING, IR_DAZZLER:NOT_RUNNING.
  • [IR/BEGIN] / [IR/CLOSE] (UART IR envelope)

    • Usage: Send [IR/BEGIN], then a single IR message body, then [IR/CLOSE] on the same UART stream to trigger a one‑off transmit.

    • Body format (.ir text block): Same fields as a standard .ir file entry (for example: name, type, protocol, address, command).

    • Body format (JSON): Single JSON object carrying the same information as a .ir entry (parsed signal fields or raw timing data).

    • Examples:

      [IR/BEGIN]
name=Power
type=parsed
protocol=NEC
addr=0x0000FFFF
cmd=0x0000E718
[IR/CLOSE]

      [IR/BEGIN]
{"name":"Power","type":"parsed","protocol":"NEC","addr":"0x0000FFFF","cmd":"0x0000E718"}
[IR/CLOSE]

    • CLI response on success: IR: send OK, followed by a compact summary:

      • Parsed: IR: signal [Name] protocol=NEC addr=0x0000FFFF cmd=0x0000E718
      • Raw: IR: signal raw len=N freq=38000Hz duty=0.33

GPS

  • gpsinfo [-s] — Stream current fix, satellites, and speed; pass -s to stop the display task.
  • startwd [-s] — Begin Wi-Fi wardriving with GPS logging, CSV output, and monitor mode; pass -s to stop and flush logs.

Settings

  • settings list — Dump available configuration keys.
  • settings help — Show supported subcommands.
  • settings get <key> / settings set <key> <value> — Inspect or change individual options.
  • settings reset [key] — Restore all settings or a specific key to defaults.