weathercli

intent

Get real-time weather data and forecasts for any location globally. Use this skill when you need current conditions (temperature, humidity, wind, precipitation), daily forecasts up to 16 days out, or hourly breakdowns for detailed planning. No API key required. Returns structured JSON or human-readable output with automatic timezone conversion.

inputs

• location string (required): city name, "city, country", "city, state/region", or coordinates. geocoding is automatic. examples: "London", "Paris, France", "Portland, Oregon".
• command type (required): one of current, forecast, or search.
• --json flag (optional): output structured JSON instead of human-readable format. use this for parsing. default: human-readable with color.
• --no-color flag (optional): strip color codes from output. useful for plain text parsing.
• --days N flag (forecast only): number of days to return. range: 1-16. default: 7.
• --hourly flag (forecast only): switch to hourly forecast mode instead of daily.
• --hours N flag (forecast + hourly): number of hours to return. range: 1-384. default: 24.
• --verbose flag (optional): log detailed request and response info.
• internet connection (required): weathercli needs network access to Open-Meteo API. offline operation not supported.
• Open-Meteo API (external, no auth): weathercli uses the free Open-Meteo weather API. no registration or API key needed. rate limits are reasonable for personal/agent use (roughly 10k requests/day per IP). hitting rate limits returns HTTP 429; back off and retry after 60 seconds.

procedure

1. parse user request - identify the location string and command type (current, forecast, search). if location is ambiguous (e.g., "Portland"), store it as-is; decision logic handles clarity in step 3.

   • input: user location string, command type
   • output: parsed location string, command identifier

2. validate location format - check that location string is non-empty and contains valid characters. reject strings longer than 256 characters or with shell injection patterns (backticks, $(), etc.).

   • input: location string from step 1
   • output: validated location string or error signal

3. execute search command (if needed for ambiguous locations) - run weathercli search "<location>" --json to get coordinates, timezone, and full location metadata. parse JSON response to extract latitude, longitude, timezone, country, and region.

   • input: location string from step 2
   • output: location object with coordinates (lat/lon), timezone, country, region, or error if not found

4. execute main command - based on command type:

   • current: run weathercli current "<location>" --json. parse JSON to extract temperature, apparent temperature, humidity, wind speed/direction, condition, precipitation, cloud cover, pressure, UV index, and timestamp.
   • forecast: run weathercli forecast "<location>" [--days N] [--hourly --hours N] --json. parse JSON to extract array of daily or hourly forecasts with temperature ranges, conditions, precipitation probability/amount, wind, UV index, sunrise/sunset (daily only).
   • input: location string, command type, flags (--json, --days, --hours, --hourly)
   • output: raw JSON response from API

5. parse JSON response - deserialize the JSON object. validate that required fields exist (location, time, temperature or forecast array). handle missing optional fields gracefully (e.g., precipitation may be 0).

   • input: JSON string from step 4
   • output: structured data object (location metadata + weather data)

6. format output - if --json flag was set, return the parsed object as JSON string. otherwise, format as human-readable text with colors, emojis, units, and local timezone labels.

   • input: structured data object from step 5, output format flag
   • output: JSON string or formatted text string

7. return result to user - deliver formatted output. include location name, timezone, and all requested fields (temperature, condition, forecast dates, etc.). if JSON, ensure it's valid and parseable.

   • input: formatted output from step 6
   • output: user-facing weather report (JSON or text)

decision points

• if location is ambiguous (e.g., "Portland" without state or country), execute the search command first to prompt for clarification or return multiple matches. if multiple matches exist and user hasn't specified, ask for country/state. if user provides "Portland, Oregon", use it directly.
• if location is not found after search, return error "location not found: ". suggest checking spelling or adding country/region context. do not proceed to weather queries.
• if network error occurs (timeout, connection refused, DNS failure), return "weather API error: network timeout". advise retry after 5-10 seconds. do not retry automatically.
• if HTTP 429 (rate limit) is returned, hold and retry after 60 seconds. if user is hammering the API in rapid succession, warn them to throttle requests.
• if JSON response is malformed or missing required fields, return parse error with details. do not attempt to fill in missing data.
• if user requests hourly forecast but provides --days flag, ignore --days and use --hours instead. hourly and daily are mutually exclusive.
• if --days N is outside range [1-16], return "invalid days value: N. must be 1-16."
• if --hours N is outside range [1-384], return "invalid hours value: N. must be 1-384."
• if user requests --hourly without --hours, default to 24 hours.
• if user requests multiple cities in one call, process each sequentially and aggregate results. if any single city fails, return that error and continue with others.

output contract

for current command:

return JSON object with this structure:

{
  "location": {
    "name": "Tokyo",
    "latitude": 35.6895,
    "longitude": 139.6917,
    "country": "Japan",
    "timezone": "Asia/Tokyo"
  },
  "time": "2026-01-12T18:45:00+09:00",
  "temperature": 4.7,
  "apparent": 1.8,
  "humidity": 66,
  "wind_speed": 3.6,
  "wind_direction": 135,
  "condition": "Clear sky",
  "weather_code": 0,
  "precipitation": 0,
  "cloud_cover": 0,
  "pressure": 1015.2,
  "uv_index": 0
}

• temperatures in Celsius
• wind speed in km/h
• times in ISO 8601 format with timezone offset
• all numeric fields present; null only if data unavailable

for forecast command:

return JSON object with this structure:

{
  "location": { ... },
  "daily": [
    {
      "date": "2026-01-12",
      "temp_max": 12.1,
      "temp_min": 4.3,
      "condition": "Slight rain",
      "precip_prob": 75,
      "precipitation": 1.5,
      "sunrise": "2026-01-12T08:04:00+09:00",
      "sunset": "2026-01-12T16:45:00+09:00",
      "wind_speed_max": 15.3,
      "wind_direction": 202,
      "uv_index_max": 2.4
    }
  ]
}

or for hourly:

{
  "location": { ... },
  "hourly": [
    {
      "time": "2026-01-12T18:00:00+09:00",
      "temperature": 5.2,
      "condition": "Clear sky",
      "precip_prob": 10,
      "precipitation": 0,
      "wind_speed": 4.1,
      "wind_direction": 140,
      "uv_index": 0
    }
  ]
}

• array length matches requested days/hours
• all fields present; missing data set to 0 or null
• times in ISO 8601 with timezone offset
• temperatures in Celsius, wind in km/h, precipitation in mm

for search command:

return JSON array:

[
  {
    "name": "Springfield, Illinois",
    "latitude": 39.7817,
    "longitude": -89.6501,
    "country": "United States",
    "region": "Illinois",
    "timezone": "America/Chicago"
  },
  {
    "name": "Springfield, Missouri",
    "latitude": 37.2089,
    "longitude": -93.2923,
    "country": "United States",
    "region": "Missouri",
    "timezone": "America/Chicago"
  }
]

human-readable output (no --json):

formatted text with colors (if terminal supports), emojis, and labeled fields. example:

Tokyo, Japan (Asia/Tokyo)
Current: 4.7°C (feels like 1.8°C)
Condition: Clear sky ☀
Humidity: 66%
Wind: 3.6 km/h from SE (135°)
Pressure: 1015.2 hPa
UV Index: 0 (low)

outcome signal

• success (current): user receives current temperature, condition, and other metrics for the requested location. timestamp is recent (within 15 minutes of request).
• success (forecast): user receives array of daily or hourly forecasts with at least 1 entry and up to requested count. each entry has temperature, condition, and precipitation data.
• success (search): user receives list of matching locations with coordinates and timezone. if ambiguous location was clarified, user sees full location name.
• success (human-readable): formatted output displays without errors, colors render correctly in terminal, units are labeled (°C, km/h, %, etc.).
• success (JSON): output is valid JSON, parseable by standard JSON parsers, contains all documented fields, no trailing commas or syntax errors.
• failure (location not found): user sees clear error message with location string and suggestion to verify spelling or add country.
• failure (network error): user sees timeout or connection error with retry guidance.
• failure (rate limit): user sees HTTP 429 error and is told to wait 60 seconds before retrying.
• failure (invalid input): user sees error describing the invalid flag value (e.g., "--days 25 out of range").