meshcore-bot/docs/command-reference.md

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
• Information Commands
• Emergency Commands
• Gaming Commands
• Entertainment Commands
• Sports Commands
• MeshCore Utility Commands
• Admin Commands

---

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.

---

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

---

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.

---

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

---

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.

---

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.

---

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.

---

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: Device handles auto-addition, bot manages capacity
• auto_manage_contacts = bot: Bot automatically adds companion contacts and manages capacity
• auto_manage_contacts = false: Manual mode - use !repeater commands to manage contacts

---

advert

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

---

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.

---

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