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, ethernet).
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 — Stops all active attacks, scans, and background tasks. Also restarts Wi-Fi if it was suspended by BLE.

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.
trackap — Track selected AP signal strength (RSSI) in real-time.
tracksta — Track selected station signal strength (RSSI) in real-time.

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 — Start, stop, or show help for SAE flood attacks.

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.

Aerial Detection

aerialscan [seconds] — Scan for aerial devices (drones, UAVs, RC controllers) using WiFi and BLE in sequential phases. Default: 30 seconds. Phase 1: WiFi scan (OpenDroneID WiFi, DJI WiFi, drone networks). Phase 2: BLE scan (OpenDroneID BLE, DJI BLE) — WiFi automatically suspended during BLE phase and restored after.
aeriallist — Display all detected aerial devices with full details including device ID, type, MAC address, vendor, signal strength (RSSI), GPS coordinates, altitude, speed, direction, operator location, and flight status.
aerialtrack <idx|mac> — Track a specific aerial device by index or MAC address (e.g., aerialtrack 0 or aerialtrack 12:34:56:78:9a:bc).
aerialstop — Stop aerial device scanning and tracking.
aerialspoof [device_id lat lon alt] — Broadcast fake drone RemoteID for testing via BLE. Without arguments, uses default test drone (GHOST-TEST at San Francisco, 100m altitude). With arguments: device ID, latitude, longitude, altitude in meters. Example: aerialspoof DRONE-1234 40.7128 -74.0060 100. Complies with ASTM F3411 OpenDroneID standard. Note: WiFi automatically suspended during broadcast, restored on stop.
aerialspoofstop — Stop broadcasting fake drone RemoteID and restore WiFi.

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.

GhostLink (Dual Communication)

commdiscovery — Start discovery mode to find other GhostESP devices.
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)

Available on boards with an onboard OLED status display or when an external status display is configured.

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

gpspin [pin] — View or set the GPS RX pin for external GPS modules. Without arguments, shows current pin. Setting persists to NVS; restart GPS commands to apply.
gpsinfo [-s] — Stream current fix, satellites, and speed; pass -s to stop the display task.
startwd [-s] — Start wardriving (logs Wi-Fi/GPS to CSV). Use -s to stop.

Ethernet

(Requires CONFIG_WITH_ETHERNET)

Connection Management

ethup — Initialize and bring up Ethernet interface; waits for link establishment and DHCP assignment.
ethdown — Deinitialize and bring down Ethernet interface.
ethinfo — Display Ethernet connection information (status, IP address, netmask, gateway, DNS servers, DHCP server).
webuiap [on|off|toggle|status] — Restrict the web UI to clients connected to the onboard AP subnet (AP-only mode).

Network Scanning

ethfp — Fingerprint network hosts using mDNS, NetBIOS, and SSDP (discovers Apple devices, Chromecasts, printers, Windows PCs, routers, smart TVs).
etharp — Perform ARP scan on local Ethernet network subnet (1-254) to discover active hosts.
ethping — Perform ICMP ping scan on local Ethernet network subnet (1-254) to find alive hosts.
ethports [ip] [all|start-end] — Scan TCP ports on a target IP address.
- Without arguments: scans common ports on gateway.
- all: scan all ports (1-65535).
- start-end: custom port range (e.g., 80-443).
- Examples: ethports, ethports 192.168.1.1, ethports 192.168.1.1 all, ethports 192.168.1.1 80-443.

Network Tools

ethdns <hostname> — Perform forward DNS lookup.
ethdns reverse <ip_address> — Perform reverse DNS lookup.
ethtrace <hostname_or_ip> [max_hops] — Perform traceroute to a target host (default: 30 hops, max: 64).
ethserv [ip_address] — Service discovery and banner grabbing on a target IP (default: gateway). Scans common services (FTP, SSH, Telnet, SMTP, HTTP, HTTPS, etc.).
ethhttp <url> [lines|all] — Send HTTP/HTTPS GET request to a server and display response.
- Default: shows first 25 lines
- [lines]: show first N lines (e.g., ethhttp http://example.com 50)
- all: show full response (e.g., ethhttp http://example.com all)
- Supports both HTTP and HTTPS (TLS 1.2)
- Examples: ethhttp http://example.com, ethhttp https://www.google.com 100, ethhttp http://192.168.1.1/index.html all
ethntp [ntp_server] — Query NTP server and synchronize system time. Default server: pool.ntp.org. Examples: ethntp, ethntp pool.ntp.org, ethntp time.google.com.

Configuration

ethconfig dhcp — Use DHCP for automatic IP assignment.
ethconfig static <ip> <netmask> <gateway> — Set static IP configuration.
- Example: ethconfig static 192.168.1.100 255.255.255.0 192.168.1.1
ethconfig show — Show current IP configuration.
ethmac — Display current MAC address.
ethmac set <xx:xx:xx:xx:xx:xx> — Set Ethernet MAC address (may require reinitialization).
- Example: ethmac set 02:00:00:00:00:01

Statistics

ethstats — Display Ethernet network statistics (link status, IP info, MAC address, packet statistics, ARP statistics).

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.