Skip to content

MeshCore Bot Commands

This document provides a comprehensive list of all available commands in the MeshCore Bot, with examples and detailed explanations.

Table of Contents

Basic Commands

test or t

Test message response to verify bot connectivity and functionality.

Usage: - test - Basic test response - test <phrase> - Test with optional phrase

Examples: 

test
t hello world

Response: Confirms message receipt with connection information.

ping

Simple ping/pong response to test bot responsiveness.

Usage: 

ping

Response: Pong!

help

Show available commands or get detailed help for a specific command.

Usage: - help - List all available commands - help <command> - Get detailed help for a specific command

Examples: 

help
help wx
help repeater

Response: Lists commands or provides detailed information about the specified command.

hello

Greeting response. Also responds to various greeting keywords.

Usage: 

hello
hi
hey
howdy
greetings

Response: Friendly greeting message.

cmd

List available commands in compact format.

Usage: 

cmd

Response: Compact list of all available commands.

version

Show the bot's current software version.

Usage: 

version

Response: Version string for the running MeshCore bot build.

status

Show current bot and radio status details.

Usage: 

status

Response: Runtime status summary (connection/health information).

Information Commands

channels

List and manage hashtag channels on the MeshCore network.

Usage: - channels - List general channels - channels list - List all channel categories - channels <category> - List channels in a specific category - channels #channel - Get information about a specific channel

Examples: 

channels
channels list
channels emergency
channels #general

Response: Lists available channels with their descriptions and usage statistics.

wx <zipcode>

Get weather information for a US zip code using NOAA data.

Aliases: weather, wxa, wxalert

Usage: 

wx <zipcode>
weather <zipcode>
wxa <zipcode>
wxalert <zipcode>

Examples: 

wx 98101
weather 90210
wxa 10001

Response: Current weather conditions, forecast for tonight/tomorrow, and active weather alerts. Includes: - Current conditions (temperature, humidity, wind, etc.) - Short-term forecast (tonight, tomorrow) - Weather alerts if any are active

Note: Weather alerts are automatically included when available.

gwx <location>

Get global weather information for any location worldwide using Open-Meteo API.

Aliases: globalweather, gwxa

Usage: 

gwx <location>
globalweather <location>
gwxa <location>

Examples: 

gwx Tokyo
gwx Paris, France
gwx London
globalweather New York
gwx 35.6762,139.6503

Response: Current weather conditions and forecast for the specified location, including: - Current temperature and conditions - Feels-like temperature - Wind speed and direction - Humidity - Dew point - Visibility - Pressure - Forecast for today/tonight and tomorrow

aqi <location>

Get Air Quality Index (AQI) information for a location.

Usage: 

aqi <location>
aqi <city>
aqi <city>, <state>
aqi <city>, <country>
aqi <latitude>,<longitude>
aqi help

Examples: 

aqi seattle
aqi greenwood
aqi vancouver canada
aqi 47.6,-122.3
aqi help

Response: Air quality data including: - US AQI value and category - European AQI (if available) - Pollutant concentrations (PM2.5, PM10, Ozone, etc.) - Health recommendations

rain <location>

Minute-level rain nowcast — tells you when precipitation is about to start or stop in the next couple hours, using Open-Meteo's 15-minutely precipitation forecast. Works worldwide with no API key.

Aliases: nowcast, snow

Usage: 

rain [city|zipcode|lat,lon]
nowcast [city|zipcode|lat,lon]
snow [city|zipcode|lat,lon]

Examples: 

rain
rain seattle
rain 98101
rain 47.6,-122.3
snow denver

Response: A single line describing the upcoming precipitation, for example: - 🌧️ Rain starting in ~25min for Seattle (~45min) — dry now, rain expected (with rough duration) - 🌧️ Rain easing in ~20min for Seattle — raining now, clearing soon - 🌧️ Heavy rain steady for 2h+ in Seattle — raining now, no break in the window - ☀️ No rain expected in next 2h for Seattle — dry through the window

The keyword sets which precipitation the answer leads with: rain/nowcast lead with rain (liquid amount), while snow leads with snowfall (reported as depth, e.g. 🌨️ Snow starting in ~40min (~1.5 in snow)). Either keyword still mentions the other type when it's in the window, and snow/ice changeovers are called out. Bare countries or US states (e.g. rain france, snow texas) default to the region's capital with a heads-up, since one centroid isn't representative.

When no location is given, uses the sender's companion location if known, then the bot's configured location.

Configuration: [Rain_Command] — enabled, window_minutes (how far ahead to look, default 120), precip_threshold_mm (sensitivity, default 0.1), and optional default_lat/default_lon. Temperature/precipitation source units are shared via [Weather] (weather_model is honored).

Note: Falls back to hourly precipitation when a weather model doesn't provide 15-minute data for the area.

airplanes [location] [options] / overhead [lat,lon]

Get aircraft tracking information using ADS-B data from airplanes.live or compatible APIs.

Aliases: aircraft, planes, adsb, overhead

Usage: 

airplanes
airplanes here
airplanes <latitude>,<longitude>
airplanes [location] [options]
overhead
overhead <latitude>,<longitude>

Special Command: overhead - Returns the single closest aircraft directly overhead - Uses companion location from database (if available) - If companion location not available, prompts user to specify coordinates - Always returns one aircraft sorted by distance (closest first)

Location Options: - No location: Uses companion location (if available), otherwise bot location - here: Uses bot location from config - <lat>,<lon>: Uses specified coordinates (e.g., 47.6,-122.3)

Filter Options: - radius=<nm> - Search radius in nautical miles (default: 25, max: 250) - alt=<min>-<max> - Filter by altitude range in feet (e.g., alt=1000-5000) - speed=<min>-<max> - Filter by ground speed range in knots - type=<code> - Filter by aircraft type code (e.g., B738, A321) - callsign=<pattern> - Filter by callsign pattern - military - Show only military aircraft - ladd - Show only LADD aircraft - pia - Show only PIA aircraft - squawk=<code> - Filter by transponder squawk code - limit=<n> - Limit number of results (default: 10, max: 50) - closest - Sort by distance (closest first) - highest - Sort by altitude (highest first) - fastest - Sort by speed (fastest first)

Examples: 

airplanes
airplanes here
airplanes 47.6,-122.3
airplanes radius=50
airplanes alt=10000-40000
airplanes type=B738
airplanes military
airplanes callsign=UAL limit=5
airplanes 47.6,-122.3 radius=25 closest

Response: - Single aircraft: Detailed format with callsign, type, altitude, speed, track, distance, bearing, vertical rate, and registration - Multiple aircraft: Compact list format with callsign, altitude, speed, distance, and bearing

Configuration: The command can be configured in config.ini under [Airplanes_Command]: - enabled - Enable/disable the command - api_url - API endpoint URL (default: http://api.airplanes.live/v2/) - default_radius - Default search radius in nautical miles - max_results - Maximum number of results to return - url_timeout - API request timeout in seconds

Note: Uses companion location from database if available, otherwise falls back to bot location from config. The API is rate-limited to 1 request per second.

sun

Get sunrise and sunset times for the bot's configured location.

Usage: 

sun

Response: Sunrise and sunset times, day length, and solar noon.

Note: Uses the bot's configured default location (bot_latitude and bot_longitude in config.ini), not the user's location from their advert.

aurora

Get aurora visibility/forecast conditions for configured or provided coordinates.

Usage: 

aurora
aurora <lat>,<lon>

Response: Aurora activity and visibility guidance for the requested location.

moon

Get moon phase information and moonrise/moonset times for the bot's configured location.

Usage: 

moon

Response: Current moon phase, moonrise/moonset times, and illumination percentage.

Note: Uses the bot's configured default location (bot_latitude and bot_longitude in config.ini), not the user's location from their advert.

solar

Get solar conditions and HF band status.

Usage: 

solar

Response: Solar activity information including: - Solar flux - Sunspot number - A-index and K-index - HF band conditions (Open/Closed/Marginal) - Solar activity summary

Data comes from HamQSL and NOAA SWPC. For the provenance of the underlying modules/solar_conditions.py implementation, see Solar conditions rewrite provenance.

solarforecast or sf

Get solar panel production forecast for a location.

Usage: 

sf <location|repeater_name|coordinates|zipcode> [panel_size] [azimuth] [angle]
solarforecast <location> [panel_size] [azimuth] [angle]

Parameters: - location - Location name, repeater name, coordinates (lat,lon), or zipcode - panel_size - Panel size in watts (optional, default: 100W) - azimuth - Panel azimuth in degrees, 0=south (optional, default: 180) - angle - Panel tilt angle in degrees (optional, default: 30)

Examples: 

sf seattle
sf seattle 200
sf seattle 200 180 45
sf 47.6,-122.3 150
sf repeater1 100 180 30

Response: Solar panel production forecast including: - Daily production estimate - Hourly production breakdown - Peak production time - Total daily kWh estimate

hfcond

Get HF band conditions for amateur radio.

Usage: 

hfcond

Response: HF band conditions including: - Band status (Open/Closed/Marginal) - Solar flux - A-index and K-index - Propagation conditions

satpass <NORAD>

Get satellite pass information for a satellite by NORAD ID.

Usage: - satpass <NORAD> - Get radio passes (all passes above horizon) - satpass <NORAD> visual - Get visual passes only (must be visually observable) - satpass <shortcut> - Use predefined shortcuts

Shortcuts: - Weather Satellites: noaa15, noaa18, noaa19, metop-a, metop-b, metop-c, goes16, goes17, goes18 - Space Stations: iss, tiangong, tiangong1, tiangong2 - Telescopes: hst, hubble - Other: starlink

Examples: 

satpass 25544
satpass iss
satpass iss visual
satpass noaa19
satpass hubble visual

Response: Upcoming satellite passes including: - Pass start/end times - Maximum elevation - Duration - Azimuth at start/end - Visual pass indicator (if applicable)

Note: Requires n2yo_api_key to be configured in config.ini.

Emergency Commands

alert <location> [all]

Get active emergency incidents for a location.

Usage: 

alert <city|zipcode|street city|lat,lon|county> [all]

Parameters: - location - City name, zipcode, street address with city, coordinates, or county name - all - Show all incidents (default: shows most relevant incidents)

Examples: 

alert seattle
alert 98101
alert main street seattle
alert 47.6,-122.3
alert seattle all
alert king county

Response: Active emergency incidents including: - Incident type and description - Location - Agency - Time - Severity level

Note: Requires Alert_Command configuration in config.ini with agency IDs for your area.

Gaming Commands

dice

Roll dice with various configurations.

Usage: - dice - Roll a standard 6-sided die (d6) - dice d<N> - Roll a die with N sides - dice <X>d<N> - Roll X dice with N sides each

Examples: 

dice
dice d20
dice 2d6
dice 3d10

Response: Shows the dice roll result(s) and total.

roll

Roll a random number within a specified range.

Usage: - roll - Roll a number between 1 and 100 - roll <max> - Roll a number between 1 and max

Examples: 

roll
roll 50
roll 1000

Response: Shows the random number result.

magic8

Ask the Magic 8-Ball a yes/no question.

Usage: 

magic8 <question>

Examples: 

magic8 will the mesh be busy tonight?
magic8 should I deploy another node?

Response: A randomized Magic 8-Ball style answer.

Entertainment Commands

joke

Get a random joke from various categories.

Usage: - joke - Get a random joke - joke <category> - Get a joke from a specific category

Examples: 

joke
joke programming
joke pun

Response: A random joke from the selected category.

dadjoke

Get a dad joke from icanhazdadjoke.com.

Usage: 

dadjoke

Response: A random dad joke.

hacker

Responds to Linux/Unix commands with supervillain mainframe error messages.

Usage: 

sudo
ps aux
grep
ls -l
cat
rm -rf

Examples: 

sudo make me a sandwich
ps aux | grep evil
ls -l /secret/base

Response: Humorous error messages in the style of a supervillain's mainframe system.

catfact

Get a random cat fact.

Usage: 

catfact

Response: A short random cat fact.

Sports Commands

sports

Get sports scores for configured teams or leagues.

Usage: - sports - Get scores for default teams - sports <team> - Get scores for a specific team - sports <league> - Get scores for a league (nfl, mlb, nba, nhl, etc.)

Examples: 

sports
sports seahawks
sports nfl
sports mlb

Response: Current scores and game information for the requested teams or league.

World Cup scores are also available year-round here, e.g. sports fifa.

wc or worldcup

FIFA World Cup scores and schedule. Responds only while a World Cup (men's or women's) is actually in progress — the active tournament is auto-detected from the ESPN schedule, so no dates need to be configured. Outside a tournament it replies that none is in progress.

Usage: - wc - Live/most recent scores and upcoming fixtures - wc <nation> - Focus on a specific nation's match

Examples: 

wc
worldcup
wc argentina

Response: Current scores, match state, and upcoming fixtures for the active tournament.

Configuration: [Worldcup_Command] — enabled, api_timeout, cache_ttl_minutes. For proactive live match announcements posted to a channel, see the World Cup Live Service.

MeshCore Utility Commands

path or decode or route

Decode and display the routing path of a message.

Usage: 

path
decode
route

Response: Shows the complete routing path the message took through the mesh network, including all intermediate nodes.

trace and tracer

Run a link trace for diagnostics. trace sends a trace along the given path (return may not be heard by the bot). tracer builds a round-trip path so the bot's radio hears the return.

Usage: - trace [path] - Trace along path (comma-separated 2-char hex, e.g. 01,7a,55). No path = use your message's incoming path. - tracer [path] - Same but path is converted to round-trip (e.g. 01,7a,55 → 01,7a,55,7a,01) so the bot hears the response.

Examples: 

trace 01,7a,55
tracer 01,7a,55
tracer
With no path, both use the path your message took to reach the bot (like the test command).

Config: [Trace_Command] — enabled, maximum_hops, trace_mode (one_byte/two_byte), timeout_base_seconds (default 1.0), timeout_per_hop_seconds (default 0.5), trace_retry_count (default 2 attempts), trace_retry_delay_seconds (default 1.0), update_graph_one_byte, update_graph_two_byte. Total wait per attempt = base + (hops × per_hop). On failure, waits then retries up to trace_retry_count times.

Response: Compact trace result: tag, hop count, SNR per hop, and optional graph update when enabled.

prefix <XX>

Look up repeaters by two-character prefix.

Usage: - prefix <XX> - Look up repeaters with the specified prefix - prefix <XX> all - Include all repeaters (not just active ones) - prefix refresh - Refresh the prefix cache - prefix free or prefix available - Show available prefixes

Examples: 

prefix 1A
prefix 2B all
prefix refresh
prefix free

Response: List of repeaters matching the prefix, including: - Repeater name - Status (active/inactive) - Last seen time - Location (if available)

stats

Show bot usage statistics for the past 24 hours.

Usage: - stats - Overall statistics - stats messages - Message statistics - stats channels - Channel statistics - stats paths - Path statistics

Examples: 

stats
stats messages
stats channels
stats paths

Response: Usage statistics including: - Total messages processed - Commands executed - Channel activity - Routing path information

multitest or mt

Listen for 6 seconds and collect all unique paths from incoming messages.

Usage: 

multitest
mt

Response: List of all unique routing paths discovered during the 6-second listening period.

Command Syntax

Prefix

Commands can be used with or without the ! prefix: - test or !test - Both work - wx 98101 or !wx 98101 - Both work

Direct Messages

Some commands work in both public channels and direct messages, while admin commands typically require direct messages for security.

Rate Limiting

The bot implements rate limiting to prevent spam. If you send commands too quickly, you may receive a rate limit message. Wait a few seconds before trying again.

Case Sensitivity

Most commands are case-insensitive: - TEST and test work the same - WX 98101 and wx 98101 work the same

Getting Help

Use the help command to get more information: - help - List all commands - help <command> - Get detailed help for a specific command

Additional Notes

Location Requirements

Some commands use location data: - sun and moon - Use the bot's configured default location (bot_latitude and bot_longitude in config.ini), not the user's location from their advert - solar - Does not require location (provides global solar conditions) - solarforecast - Requires a location parameter (location name, repeater name, coordinates, or zipcode) - wx - Requires a zipcode parameter - gwx - Requires a location parameter - aqi - Requires a location parameter

API Keys

Some commands require API keys to be configured in config.ini: - satpass - Requires n2yo_api_key - aqi - Requires airnow_api_key (optional, uses fallback if not configured)

Weather Data

  • wx uses NOAA API (US locations only)
  • gwx uses Open-Meteo API (global locations)
  • Both provide current conditions and forecasts

Command Categories

Commands are organized into categories for easier discovery: - Basic - Essential commands for testing and help - Information - Weather, astronomy, and data queries - Emergency - Emergency and safety information - Gaming - Fun commands for games and random numbers - Entertainment - Jokes and humorous responses - Sports - Sports scores and information - MeshCore Utility - Network-specific utilities - Admin - Administrative commands (DM only)

Admin Commands

Note: Admin commands are only available via Direct Message (DM) and may require ACL permissions.

repeater or repeaters or rp

Manage repeater contacts and contact list capacity.

Usage: 

repeater <subcommand> [options]
repeaters <subcommand> [options]
rp <subcommand> [options]

Repeater Management Subcommands

  • scan - Scan current contacts and catalog new repeaters
  • list - List repeater contacts (use --all to show purged ones)
  • locations - Show location data status for repeaters
  • update-geo - Update missing geolocation data (state/country) from coordinates
  • update-geo dry-run - Preview what would be updated without making changes
  • update-geo <N> - Update up to N repeaters (default: 10)
  • update-geo dry-run <N> - Preview updates for up to N repeaters
  • purge all - Purge all repeaters
  • purge all force - Force purge all repeaters (uses multiple removal methods)
  • purge <days> - Purge repeaters older than specified days
  • purge <name> - Purge specific repeater by name
  • restore <name> - Restore a previously purged repeater
  • stats - Show repeater management statistics

Contact List Management Subcommands

  • status - Show contact list status and limits
  • manage - Manage contact list to prevent hitting limits
  • manage --dry-run - Show what management actions would be taken
  • add <name> [key] - Add a discovered contact to contact list
  • auto-purge - Show auto-purge status and controls
  • auto-purge trigger - Manually trigger auto-purge
  • auto-purge enable/disable - Enable/disable auto-purge
  • purge-status - Show detailed purge status and recommendations
  • test-purge - Test the improved purge system
  • discover - Discover companion contacts
  • auto <on|off> - Toggle manual contact addition setting
  • test - Test meshcore-cli command functionality

Examples: 

repeater scan
repeater status
repeater manage
repeater manage --dry-run
repeater add "John"
repeater discover
repeater auto-purge
repeater auto-purge trigger
repeater purge-status
repeater purge all
repeater purge 30
repeater stats

Response: Varies by subcommand. Provides information about repeater contacts, contact list capacity, and management actions.

Note: This system helps manage both repeater contacts and overall contact list capacity. It automatically removes stale contacts and old repeaters when approaching device limits.

Automatic Features: - NEW_CONTACT events are automatically monitored - Repeaters are automatically cataloged when discovered - Contact list capacity is monitored in real-time - auto_manage_contacts = device (default): Firmware auto-adds chat (companion) peers only, with overwrite oldest non-favourite when the contact table is full; the bot schedules delayed jobs to set that firmware policy and to favourite keys in Admin_ACL plus the effective announcements ACL (same rules as the announcements command), then clear favourite on other contacts. The bot still runs capacity management on NEW_CONTACT (near-limit manage_contact_list) and does not call add_contact for new companions itself. Contact limit for logging and capacity is taken from the radio’s max_contacts and, if the live table is larger (under-reported max), raised to match the mesh so counts are not shown as over-capacity. Companion auto-purge never runs on the radio in this mode. Count-based repeater auto-purge only runs if the table grows strictly above that synced limit (normally off while the firmware manages slots). - auto_manage_contacts = bot: Bot adds new companions via add_contact (full NEW_CONTACT payload), runs manage-before-add when the list is near limit, and retries once after manage_contact_list if the radio returns TABLE_FULL. - auto_manage_contacts = false: Manual mode - NEW_CONTACT companions are tracked in the database only; use !repeater commands to manage the device list.

Send a network flood advert to announce the bot's presence on the mesh network.

Usage: 

advert

Response: Confirms that the advert was sent.

Note: - DM only command - 1-hour cooldown period between uses - Sends a flood advert to all nodes on the network

reload

Reload supported runtime configuration without restarting the bot.

Usage: 

reload

Response: Confirms reload success or reports validation/loading errors.

Note: Admin DM command. Connection/radio settings still require a process restart.

channelpause / channelresume

Temporarily pause or resume bot reactions on public channels.

Usage: 

channelpause
channelresume

Response: Confirms whether channel handling is paused or resumed.

Note: Admin DM command. DMs continue to work while channel responses are paused.

greeter

Show greeter behavior and configuration guidance.

Usage: 

greeter

Response: Describes greeter mode and points to [Greeter_Command] settings in config.

feed

Manage RSS feed and API feed subscriptions (Admin only).

Usage: 

feed <subcommand> [options]

Subcommands

  • subscribe <rss|api> <url> <channel> [name] - Subscribe to a feed
  • unsubscribe <id|url> <channel> - Unsubscribe from a feed
  • list [channel] - List all subscriptions
  • status <id> - Get status of a specific subscription
  • test <url> - Test a feed URL
  • enable <id> - Enable a subscription
  • disable <id> - Disable a subscription
  • update <id> [interval_seconds] - Update subscription interval

Examples: 

feed subscribe rss https://alerts.example.com/rss emergency "Emergency Alerts"
feed subscribe api https://api.example.com/alerts emergency "API Alerts" '{"headers": {"Authorization": "Bearer TOKEN"}}'
feed list
feed status 1
feed test https://example.com/feed.xml

Response: Confirmation of the action or list of subscriptions.

Note: Admin access required. Feeds are automatically checked and posted to the specified channel.

announcements

Manage announcement ACL and related announcement settings.

Usage: 

announcements <subcommand> [args]

Response: Shows current announcement ACL or confirms changes.

Note: Admin access required.

schedule

View configured scheduled messages and advert interval.

Usage: 

schedule

Response: Lists configured scheduled posts (each line shows the cron or preset schedule, or legacy HH:MM if you still use deprecated HHMM keys) plus current advert timing.

Note: DM-only command by default. Cron day-of-week uses APScheduler numbering (0=Monday), not Vixie cron — see Scheduled messages.

webviewer or web or viewer or wv

Manage the web viewer integration.

Usage: 

webviewer <subcommand>

Subcommands:

Subcommand Description
status Report enabled/running state, URL, circuit-breaker state, failure count, and shutdown state
reset Reset the integration's circuit breaker after repeated failures
restart Restart the web viewer process

Response: A compact status line, or confirmation that the reset or restart was initiated.

Note: DM-only command. Disable with enabled = false under [WebViewer_Command].

For more information about configuring the bot, see the main README file.