-
Notifications
You must be signed in to change notification settings - Fork 419
CLI Reference
Martin Gergeleit edited this page Mar 13, 2026
·
7 revisions
For configuration you have to use a serial console (Putty or GtkTerm with 115200 bps). Use the "set_sta" and the "set_ap" command to configure the WiFi settings. Changes are stored persistently in NVS and are applied after next restart. Use "show" commands to display the current config.
Enter the help command get a full list of all available commands:
help [<string>] [-v <0|1>]
Print the summary of all registered commands if no arguments are given,
otherwise print summary of given command.
<string> Name of command
-v, --verbose=<0|1> If specified, list console commands with given verbose level
heap
Get current and size of free heap memory and the minimum that was available
during program execution
version
Get version of chip and SDK
restart
Software reset of the chip
factory_reset
Erase all settings (NVS namespace 'esp32_nat') and restart
deep_sleep [-t <t>] [--io=<n>] [--io_level=<0|1>]
Enter deep sleep mode. Two wakeup modes are supported: timer and GPIO. If no
wakeup option is specified, will sleep indefinitely.
-t, --time=<t> Wake up time, ms
--io=<n> If specified, wakeup using GPIO with given number
--io_level=<0|1> GPIO level to trigger wakeup
light_sleep [-t <t>] [--io=<n>]... [--io_level=<0|1>]...
Enter light sleep mode. Two wakeup modes are supported: timer and GPIO.
Multiple GPIO pins can be specified using pairs of 'io' and 'io_level'
arguments. Will also wake up on UART input.
-t, --time=<t> Wake up time, ms
--io=<n> If specified, wakeup using GPIO with given number
--io_level=<0|1> GPIO level to trigger wakeup
log_level [<level>] [-t <tag>]
Get/set logging level. Without arguments shows usage. Use -t to set level for a specific tag.
<level> Log level: none/error/warn/info/debug/verbose (or 0-5)
-t, --tag=<tag> Set level for specific tag only
ping <host> [-c <n>] [-i <ms>] [-W <ms>] [-s <bytes>]
Send ICMP echo requests to a network host
<host> Host address or IP to ping
-c, --count=<n> Number of pings (default 5)
-i, --interval=<ms> Interval in ms (default 1000)
-W, --timeout=<ms> Timeout in ms (default 1000)
-s, --size=<bytes> Payload size (default 64)
tasks
Get information about running tasks
show [status|config|mappings|acl|vpn|ota]
Show router status, config, mappings, ACL rules, VPN or OTA info
[status|config|mappings|acl|vpn|ota] Type of information
set_sta <ssid> <passwd> [-u <ent_username>] [-a <ent_identity>] [-e <0-3>] [-p <0-3>] [-c <0|1>] [-t <0|1>]
Set SSID and password of the STA interface
<ssid> SSID
<passwd> Password
-u, --username=<ent_username> Enterprise username
-a, --identity=<ent_identity> Enterprise identity
-e, --eap=<0-3> EAP method (0=Auto, 1=PEAP, 2=TTLS, 3=TLS)
-p, --phase2=<0-3> TTLS phase2 (0=MSCHAPv2, 1=MSCHAP, 2=PAP, 3=CHAP)
-c, --cert-bundle=<0|1> Use CA cert bundle for server validation
-t, --no-time-check=<0|1> Skip certificate time check
set_sta_static <ip> <subnet> <gw>
Set Static IP for the STA interface
<ip> IP
<subnet> Subnet Mask
<gw> Gateway Address
set_sta_static dhcp
Clear static IP settings and revert to DHCP (requires restart)
set_sta_mac <octet> <octet> <octet> <octet> <octet> <octet>
Set MAC address of the STA interface
<octet> First octet
<octet> Second octet
<octet> Third octet
<octet> Fourth octet
<octet> Fifth octet
<octet> Sixth octet
scan
Scan for available WiFi networks
On ESP32-C5, shows an additional Band column (2.4G/5G) for each network.
set_sta_band [auto|2.4|5]
Set STA band preference (ESP32-C5 only)
auto Connect to strongest signal regardless of band (default)
2.4 Prefer 2.4 GHz networks
5 Prefer 5 GHz networks
Without arguments, shows current setting. Requires restart.
The router scans for the configured SSID and selects the best BSSID
on the preferred band, falling back to the other band if unavailable.
set_ap <ssid> <passwd>
Set SSID and password of the SoftAP
<ssid> SSID of AP
<passwd> Password of AP
set_ap_ip <ip>
Set IP for the AP interface
<ip> IP
set_ap_dns <dns>
Set DNS server for AP clients (empty to use upstream)
<dns> DNS server IP (empty string to clear)
set_ap_hidden
Hide or show the AP SSID (on/off, requires restart)
set_ap_auth [wpa2|wpa3|wpa2wpa3]
Set AP authentication mode (requires restart)
Without arguments, shows the current mode.
wpa2wpa3 = WPA2/WPA3 transitional (default), wpa2 = WPA2 only, wpa3 = WPA3 only
set_ap_mac <octet> <octet> <octet> <octet> <octet> <octet>
Set MAC address of the AP interface
<octet> First octet
<octet> Second octet
<octet> Third octet
<octet> Fourth octet
<octet> Fifth octet
<octet> Sixth octet
dhcp_reserve [add|del|block] <mac> [<ip>] [-- <name>]
Add/delete DHCP reservation or block a client by MAC
[add|del|block] add, delete, or block
<mac> MAC address (AA:BB:CC:DD:EE:FF)
<ip> IP address (required for add, use 0.0.0.0 to block)
--, -n, ----name=<name> optional device name
portmap [add|del] [TCP|UDP] <ext_portno> <int_ip> <int_portno> [STA|VPN]
Add or delete a portmapping to the router
[add|del] add or delete portmapping
[TCP|UDP] TCP or UDP port
<ext_portno> external port number
<int_ip> internal IP or device name
<int_portno> internal port number
[STA|VPN] interface to bind to (default: STA)
acl <list> <proto> <src> [<s_port>] <dst> [<d_port>] <action>
Manage firewall ACL rules
acl <list> <proto> <src> [<s_port>] <dst> [<d_port>] <action> - Add rule
acl <list> del <index> - Delete rule at index
acl <list> clear - Clear all rules from list
acl <list> clear_stats - Clear statistics for list
Lists: to_esp, from_esp, to_ap, from_ap
Protocols: IP, TCP, UDP, ICMP
Actions: allow, deny, allow_monitor, deny_monitor
bytes [[reset]]
Show or reset STA interface byte counts
[reset] reset byte counts or show current counts
pcap <action> [<mode>] [<bytes>]
Control PCAP packet capture (TCP port 19000)
<action> mode|status|snaplen|start|stop
<mode> off|acl|promisc
<bytes> snaplen value (64-1600)
web_ui <enable|disable|port>
Manage the web interface
web_ui - Show current status
web_ui enable - Enable web interface (after reboot)
web_ui disable - Disable web interface (after reboot)
web_ui port <port> - Set web server port (default 80, after reboot)
set_router_password
Set router password for web and remote console (empty string to disable)
set_led_gpio
Set GPIO for status LED (use 'none' to disable)
set_led_lowactive
Set LED to low-active (inverted) mode for active-low LEDs
set_led_strip <gpio_number|none>
Set GPIO for addressable LED strip (WS2812/SK6812)
<gpio_number> GPIO pin for WS2812 data line (0-48)
none Disable addressable LED strip (default)
Without arguments, shows current setting. Requires restart.
set_hostname <name>
Set DHCP client hostname for upstream network (empty to use default)
<name> Hostname (letters, digits, hyphens; max 32 chars)
set_ttl
Set TTL override for upstream STA packets (0 = disabled)
set_rf_switch_XIAO <0|1>
XIAO ESP32-C6 only: switch between built-in ceramic antenna (0) and external antenna (1)
Uses GPIO3 (RF switch enable) and GPIO14 (antenna select). Default: 0 (built-in).
Setting is saved to NVS and applied on every boot.
set_vpn <private_key> <public_key> <endpoint> <address> [-k <psk>] [-m <mask>] [-p <port>] [-a <keepalive>] [-e <0|1>] [-K <0|1>] [-R <0|1>]
Configure WireGuard VPN tunnel
<private_key> WireGuard private key (base64)
<public_key> Peer public key (base64)
<endpoint> Peer endpoint host/IP
<address> Tunnel IP address (e.g. 10.0.0.2)
-k, --psk Preshared key (optional)
-m, --mask Tunnel netmask (default: 255.255.255.0)
-p, --port Peer UDP port (default: 51820)
-a, --keepalive Persistent keepalive seconds (0 = disabled)
-e, --enable Enable VPN (0 or 1)
-K, --killswitch Block AP client internet when VPN down (default: 1)
remote_console <action> [<args>]
Manage remote console (network CLI access)
remote_console status - Show status and connection info
remote_console enable - Enable remote console
remote_console disable - Disable remote console
remote_console port <port> - Set TCP port (default: 2323)
remote_console bind <ap,sta,vpn> - Set interface binding
remote_console timeout <seconds> - Set idle timeout (0=none)
remote_console kick - Disconnect current session
syslog <action> [<args>]
Manage remote syslog forwarding
syslog status - Show syslog configuration
syslog enable <server> [<port>] - Enable syslog (default port 514)
syslog disable - Disable syslog forwarding
set_tz <TZ string>
Set timezone (POSIX TZ string)
set_tz - Show current timezone
set_tz <TZ string> - Set timezone
set_tz clear - Clear timezone (revert to UTC)
The set_tz command uses POSIX TZ strings in the format STDoffsetDST,start,end:
| Example | Region |
|---|---|
CET-1CEST,M3.5.0/2,M10.5.0/3 |
Central Europe (Berlin, Paris) |
EET-2EEST,M3.5.0/3,M10.5.0/4 |
Eastern Europe (Helsinki, Athens) |
GMT0BST,M3.5.0/1,M10.5.0 |
UK |
EST5EDT,M3.2.0,M11.1.0 |
US Eastern |
CST6CDT,M3.2.0,M11.1.0 |
US Central |
MST7MDT,M3.2.0,M11.1.0 |
US Mountain |
PST8PDT,M3.2.0,M11.1.0 |
US Pacific |
JST-9 |
Japan (no DST) |
AEST-10AEDT,M10.1.0,M4.1.0/3 |
Australia Eastern |
UTC |
UTC |
Note: The offset sign is inverted from what you might expect. UTC+1 (Central Europe) is written as -1 because POSIX defines it as hours west of UTC.
The timezone is persisted in NVS and restored on boot. It affects syslog timestamps and any other time display.
If you want to enter non-ASCII or special characters (incl. ' ') you can use HTTP-style hex encoding (e.g. "My%20AccessPoint" results in a string "My AccessPoint").
All newer ESP32 boards have a built in USB Serial/JTAG Controller. If the USB port is connected directly to the USB Serial/JTAG Controller, you wont be able to use the console over UART.
You can change the console output to USB_SERIAL_JTAG:
Menuconfig:
Component config -> ESP System Settings -> Channel for console output -> USB Serial/JTAG Controller
Changing sdkconfig directly
CONFIG_ESP_CONSOLE_UART_DEFAULT=n
CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y