Skip to content

CLI Reference

Jump to bottom
Martin Gergeleit edited this page Apr 9, 2026 · 11 revisions

CLI Reference

Connect via serial console (Putty or GtkTerm) at 115200 bps. Changes are stored persistently in NVS and take effect after restart unless noted otherwise.

Use help [<command>] to get built-in help for any command.

System & Diagnostics

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

version
  Get version of chip and SDK

restart
  Software reset of the chip

factory_reset
  Erase all settings (NVS namespace 'esp32_nat') and restart

heap
  Get current and size of free heap memory and the minimum that was available
  during program execution

tasks
  Get information about running tasks

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)

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

Status & Monitoring

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
  status includes: uptime, uplink connection, IPs, byte counts, AP interface state, connected clients

bytes  [[reset]]
  Show or reset STA interface byte counts
       [reset]  reset byte counts or show current counts

WiFi — STA (Upstream / Uplink)

scan
  Scan for available WiFi networks
  On ESP32-C5, shows an additional Band column (2.4G/5G) for each network.

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 through sixth octet

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.

WiFi — AP (Hotspot)

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_channel  [<0-13>]
  Set AP WiFi channel. Only available in Ethernet-uplink builds.
  0 = auto (default), 1-13 = fixed channel. Requires restart.
  Without arguments, shows current setting.

set_ap_mac  <octet> <octet> <octet> <octet> <octet> <octet>
  Set MAC address of the AP interface
       <octet>  First through sixth octet

ap   <enable|disable>
  Enable or disable the AP interface immediately (no reboot required)
  ap          - Show current AP status
  ap enable   - Enable the AP interface and persist the setting
  ap disable  - Disable the AP interface and persist the setting

DHCP & Port Mapping

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)

Firewall (ACL)

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

See Firewall for detailed usage and examples.

VPN (WireGuard)

set_vpn  <private_key> <public_key> <endpoint> <address> [-k <psk>] [-m <mask>] [-p <port>] [-a <keepalive>] [-e <0|1>] [-K <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)

See WireGuard VPN for setup instructions.

Packet Capture

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)

See Packet Capture for Wireshark integration details.

Web Interface

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)
  web_ui bind <ap|sta|vpn|all>   - Set allowed interfaces (immediate)
  
set_router_password
  Set router password for web and remote console (empty string to disable)

Remote Access

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

See Remote Console for details.

Logging

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

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

See Syslog for details.

Network Settings

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_tx_power  <dBm>
  Set WiFi TX power in dBm (2-20, 0 = max/default)
        <dBm>  TX power: 2, 5, 7, 8, 11, 13, 14, 15, 16, 18, 20 (0 = max/default)
  Without arguments, shows current and saved TX power.
  Non-zero values are applied immediately and saved for reboot.
  Setting 0 reverts to max power on next restart.

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)

Hardware & LED

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_oled  <enable|disable>
  Enable or disable OLED display (ESP32-C3 and ESP32-S3 only)
  set_oled              - Show current status
  set_oled enable       - Enable OLED display (after reboot)
  set_oled disable      - Disable OLED display (after reboot)

set_oled_gpio  <sda> <scl>
  Set I2C GPIO pins for OLED display (ESP32-C3 and ESP32-S3 only, requires restart)
       <sda>  SDA GPIO number (0-48)
       <scl>  SCL GPIO number (0-48)
  Without arguments, shows current pin assignment.

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.

Timezone Reference

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.

Special Characters

If you want to enter non-ASCII or special characters (incl. spaces) you can use HTTP-style hex encoding. For example, My%20AccessPoint results in the string My AccessPoint.

Console Output: UART vs USB Serial/JTAG

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 won't 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

Board comparison list

ESP32 NAT Router

Clone this wiki locally
⚡