Skip to content

SKILL.md

Latest commit

 

History

History
1010 lines (823 loc) · 31.3 KB

SKILL.md

File metadata and controls

1010 lines (823 loc) · 31.3 KB
name weather
description Get weather data (current conditions, forecasts, historical data, alerts) for any location. No API key required. Use when you need current weather, hourly/daily forecasts, historical weather, or severe weather alerts.
context fork
allowed-tools
Bash(weather current *)
Bash(weather forecast *)
Bash(weather alerts *)
Bash(weather history *)
Bash(weather providers *)
Bash(weather cache *)
Bash(weather init *)
Bash(weather --version)
Bash(weather --help)
Bash(weather current --help)
Bash(weather forecast --help)
Bash(weather alerts --help)
Bash(weather history --help)
Bash(weather providers --help)
Bash(weather cache --help)
Bash(weather auth *)
Bash(weather auth --help)
Bash(weather auth set --help)
Bash(weather auth remove --help)
Bash(weather auth status --help)

weather — Weather CLI for Agents and Scripting

A Rust CLI that provides weather data (current conditions, forecasts, historical data, alerts) from free APIs, with JSON and plain-text output optimized for parsing by scripts and AI agents.

Use this tool when you need: current weather conditions, hourly/daily forecasts, historical weather data, or severe weather alerts for a location. No API key required for basic functionality.

Installation

# Build from source
cargo build --release

# Binary location
./target/release/weather

# First-time setup (creates config file)
weather init

Quick Reference

# Current weather for a city
weather current "London"

# Current weather by coordinates
weather current --lat 51.5 --lon -0.12

# Hourly forecast (next 24 hours, default)
weather forecast hourly "London"

# Daily forecast (next 7 days, default)
weather forecast daily "London"

# Weather alerts (US locations only, via NWS)
weather alerts "New York"

# Historical weather for a specific date
weather history "London" --date 2024-06-15

# Historical weather for a date range
weather history "London" --from 2024-06-01 --to 2024-06-07

# List configured providers
weather providers

# Cache management
weather cache stats
weather cache clear

# Set an API key for a provider
weather auth set openweathermap "your-api-key-here"

# Check which providers have keys configured
weather auth status

# Remove an API key
weather auth remove openweathermap

# Force plain text (TSV) output
weather current "London" --plain

# Use imperial units
weather --units imperial current "London"

# Force a specific provider
weather --provider openmeteo current "London"

Commands

init

Initialize configuration. Creates the config file with default settings.

weather init

JSON output:

{
  "message": "Configuration initialized at: /tmp/weather-cli-config/config.toml",
  "path": "/tmp/weather-cli-config/config.toml",
  "timestamp": "2026-02-06T22:11:25.631953+00:00"
}

Note: The path value is system-dependent. On macOS it uses ~/Library/Application Support/weather-cli/config.toml; on Linux it uses ~/.config/weather-cli/config.toml. Override with WEATHER_CLI_CONFIG_DIR.

JSON schema:

Field Type Description
message string Human-readable confirmation message
path string Absolute path to the created config file
timestamp string ISO 8601 timestamp of the operation

Plain output (TSV):

message	path	timestamp
Configuration initialized at: /tmp/weather-cli-config/config.toml	/tmp/weather-cli-config/config.toml	2026-02-06T22:11:25.631953+00:00

current

Get current weather conditions for a location.

Syntax:

weather current <LOCATION>
weather current --lat <LAT> --lon <LON>
weather current --zip <ZIP> [--country <CC>]
weather current --airport <IATA>

Location inputs: city name, coordinates, ZIP code, airport IATA code.

Example:

weather current "London" --json

JSON output:

{
  "conditions": "Partly cloudy",
  "feels_like": 7.5,
  "feels_like_unit": "°C",
  "humidity": 84.0,
  "location": {
    "country": "United Kingdom",
    "latitude": 51.50853,
    "longitude": -0.12574,
    "name": "London",
    "timezone": "Europe/London"
  },
  "pressure": 989.2,
  "pressure_unit": "hPa",
  "provider": "Open-Meteo",
  "temperature": 9.6,
  "temperature_unit": "°C",
  "timestamp": "2026-02-06T22:00:00+00:00",
  "wind_direction": 215.0,
  "wind_speed": 8.8,
  "wind_speed_unit": "km/h"
}

JSON schema:

Field Type Description
conditions string Human-readable weather description
feels_like number Apparent temperature
feels_like_unit string Unit for feels_like (e.g., "°C", "°F")
humidity number Relative humidity (%)
location object Location details (see Location object below)
pressure number Atmospheric pressure
pressure_unit string Unit for pressure (e.g., "hPa")
provider string Weather data provider name
temperature number Current temperature
temperature_unit string Unit for temperature (e.g., "°C", "°F")
timestamp string ISO 8601 timestamp of the observation
wind_direction number Wind direction in degrees
wind_speed number Wind speed
wind_speed_unit string Unit for wind_speed (e.g., "km/h", "mph", "m/s")

Location object schema (shared by all commands that include a location field):

Field Type Description
location.country string|null Country name
location.latitude number Latitude
location.longitude number Longitude
location.name string Location name
location.timezone string|null IANA timezone

Plain output (TSV):

location	temperature(°C)	feels_like(°C)	humidity	pressure(hPa)	wind_speed(km/h)	wind_direction	conditions	provider	timestamp
London	9.6	7.5	84	989.2	8.8	215	Partly cloudy	Open-Meteo	2026-02-06T22:11:45.720704+00:00

forecast hourly

Get hourly weather forecast.

Syntax:

weather forecast hourly <LOCATION> [--hours <N>]
weather forecast hourly --lat <LAT> --lon <LON> [--hours <N>]

Location inputs: city name, coordinates only. No ZIP or airport support.

Flags:

  • --hours <N> — Number of hours to forecast. Default: 24. Range: 1–168.

Example:

weather forecast hourly "London" --hours 2 --json

JSON output:

{
  "hours": [
    {
      "conditions": "Partly cloudy",
      "humidity": 84.0,
      "precipitation": 0.0,
      "precipitation_probability": 0.0,
      "temperature": 9.6,
      "temperature_unit": "°C",
      "time": "2026-02-06T22:00:00+00:00",
      "wind_direction": 215.0,
      "wind_speed": 8.8,
      "wind_speed_unit": "km/h"
    },
    {
      "conditions": "Partly cloudy",
      "humidity": 87.0,
      "precipitation": 0.0,
      "precipitation_probability": 0.0,
      "temperature": 9.0,
      "temperature_unit": "°C",
      "time": "2026-02-06T23:00:00+00:00",
      "wind_direction": 194.0,
      "wind_speed": 5.9,
      "wind_speed_unit": "km/h"
    }
  ],
  "location": {
    "country": "United Kingdom",
    "latitude": 51.50853,
    "longitude": -0.12574,
    "name": "London",
    "timezone": "Europe/London"
  },
  "provider": "Open-Meteo",
  "timestamp": "2026-02-06T22:12:06.132217+00:00"
}

JSON schema (top level):

Field Type Description
hours array Array of hourly data points (see element schema below)
location object Location details (see Location object schema under current)
provider string Weather data provider name
timestamp string ISO 8601 request timestamp

JSON schema for each element in hours array:

Field Type Description
time string ISO 8601 timestamp
temperature number Temperature
temperature_unit string Unit for temperature
conditions string Weather description
precipitation_probability number Probability of precipitation (%)
precipitation number Precipitation amount (mm)
wind_speed number Wind speed
wind_speed_unit string Unit for wind_speed
wind_direction number Wind direction in degrees
humidity number Relative humidity (%)

Plain output (TSV):

time	temperature(°C)	conditions	precip_prob(%)	precipitation(mm)	wind_speed(km/h)	wind_dir	humidity(%)	timestamp
2026-02-06T22:00:00+00:00	9.6	Partly cloudy	0	0	8.8	215	84	2026-02-06T22:12:09.416949+00:00
2026-02-06T23:00:00+00:00	9	Partly cloudy	0	0	5.9	194	87	2026-02-06T22:12:09.416949+00:00

forecast daily

Get daily weather forecast.

Syntax:

weather forecast daily <LOCATION> [--days <N>]
weather forecast daily --lat <LAT> --lon <LON> [--days <N>]

Location inputs: city name, coordinates only. No ZIP or airport support.

Flags:

  • --days <N> — Number of days to forecast. Default: 7. Range: 1–16.

Example:

weather forecast daily "London" --days 2 --json

JSON output:

{
  "days": [
    {
      "conditions": "Slight rain showers",
      "date": "2026-02-06",
      "precipitation_probability": 100.0,
      "precipitation_sum": 6.4,
      "sunrise": "2026-02-06T07:30:00+00:00",
      "sunset": "2026-02-06T16:58:00+00:00",
      "temperature_high": 11.3,
      "temperature_low": 7.7,
      "temperature_unit": "°C",
      "wind_speed_max": 13.7,
      "wind_speed_unit": "km/h"
    },
    {
      "conditions": "Slight rain showers",
      "date": "2026-02-07",
      "precipitation_probability": 75.0,
      "precipitation_sum": 0.6,
      "sunrise": "2026-02-07T07:28:00+00:00",
      "sunset": "2026-02-07T17:00:00+00:00",
      "temperature_high": 10.7,
      "temperature_low": 8.7,
      "temperature_unit": "°C",
      "wind_speed_max": 16.3,
      "wind_speed_unit": "km/h"
    }
  ],
  "location": {
    "country": "United Kingdom",
    "latitude": 51.50853,
    "longitude": -0.12574,
    "name": "London",
    "timezone": "Europe/London"
  },
  "provider": "Open-Meteo",
  "timestamp": "2026-02-06T22:12:13.140805+00:00"
}

JSON schema (top level):

Field Type Description
days array Array of daily data points (see element schema below)
location object Location details (see Location object schema under current)
provider string Weather data provider name
timestamp string ISO 8601 request timestamp

JSON schema for each element in days array:

Field Type Description
date string Date in YYYY-MM-DD format
temperature_high number Maximum temperature
temperature_low number Minimum temperature
temperature_unit string Unit for temperature
conditions string Weather description
precipitation_sum number Total precipitation (mm)
precipitation_probability number Max probability of precipitation (%)
sunrise string ISO 8601 sunrise time
sunset string ISO 8601 sunset time
wind_speed_max number Maximum wind speed
wind_speed_unit string Unit for wind_speed

Plain output (TSV):

date	high(°C)	low(°C)	conditions	precip(mm)	precip_prob(%)	sunrise	sunset	wind_speed_max(km/h)	timestamp
2026-02-06	11.3	7.7	Slight rain showers	6.4	100	2026-02-06T07:30:00+00:00	2026-02-06T16:58:00+00:00	13.7	2026-02-06T22:12:16.885723+00:00
2026-02-07	10.7	8.7	Slight rain showers	0.6	75	2026-02-07T07:28:00+00:00	2026-02-07T17:00:00+00:00	16.3	2026-02-06T22:12:16.885723+00:00

alerts

Get active weather alerts for a location. Alerts are sourced from the US National Weather Service (NWS). Non-US locations return an empty alerts array.

Syntax:

weather alerts <LOCATION>
weather alerts --lat <LAT> --lon <LON>

Location inputs: city name, coordinates only. No ZIP or airport support.

Important: Only US locations have alert data. Non-US locations always return "alerts": [].

Example:

weather alerts "New York" --json

JSON output (with active alerts):

{
  "alerts": [
    {
      "description": "* WHAT...For the Wind Advisory, northwest winds 20 to 30 mph with\ngusts up to 50 mph expected. For the Extreme Cold Warning,\ndangerously cold wind chills as low as 20 below expected.\n\n* WHERE...Portions of northeast New Jersey and southeast New York.\n\n* WHEN...For the Wind Advisory, from 9 AM Saturday to midnight EST\nSaturday Night. For the Extreme Cold Warning, from 10 AM Saturday\nto 1 PM EST Sunday.\n\n* IMPACTS...Gusty winds will blow around unsecured objects. Tree\nlimbs could be blown down and a few power outages may result. The\ncold wind chills could cause frostbite on exposed skin in as\nlittle as 30 minutes.",
      "effective": "2026-02-06T13:22:00-05:00",
      "event": "Wind Advisory",
      "expires": "2026-02-07T05:00:00-05:00",
      "headline": "Wind Advisory issued February 6 at 1:22PM EST until February 8 at 12:00AM EST by NWS Upton NY",
      "severity": "moderate",
      "source": "NWS Upton NY"
    },
    {
      "description": "* WHAT...For the Wind Advisory, northwest winds 20 to 30 mph with\ngusts up to 50 mph expected. For the Extreme Cold Warning,\ndangerously cold wind chills as low as 20 below expected.\n\n* WHERE...Portions of northeast New Jersey and southeast New York.\n\n* WHEN...For the Wind Advisory, from 9 AM Saturday to midnight EST\nSaturday Night. For the Extreme Cold Warning, from 10 AM Saturday\nto 1 PM EST Sunday.\n\n* IMPACTS...Gusty winds will blow around unsecured objects. Tree\nlimbs could be blown down and a few power outages may result. The\ncold wind chills could cause frostbite on exposed skin in as\nlittle as 30 minutes.",
      "effective": "2026-02-06T13:22:00-05:00",
      "event": "Extreme Cold Warning",
      "expires": "2026-02-07T05:00:00-05:00",
      "headline": "Extreme Cold Warning issued February 6 at 1:22PM EST until February 8 at 1:00PM EST by NWS Upton NY",
      "severity": "severe",
      "source": "NWS Upton NY"
    }
  ],
  "location": {
    "country": "United States",
    "latitude": 40.71427,
    "longitude": -74.00597,
    "name": "New York",
    "timezone": "America/New_York"
  },
  "provider": "Open-Meteo",
  "timestamp": "2026-02-06T22:12:24.970557+00:00"
}

JSON output (no active alerts — e.g., non-US location):

{
  "alerts": [],
  "location": {
    "country": "United Kingdom",
    "latitude": 51.50853,
    "longitude": -0.12574,
    "name": "London",
    "timezone": "Europe/London"
  },
  "provider": "Open-Meteo",
  "timestamp": "2026-02-06T22:12:28.733631+00:00"
}

JSON schema (top level):

Field Type Description
alerts array Array of alert objects (empty if no active alerts)
location object Location details (see Location object schema under current)
provider string Weather data provider name
timestamp string ISO 8601 request timestamp

JSON schema for each element in alerts array:

Field Type Description
event string Alert event type (e.g., "Winter Storm Warning")
severity string One of: "extreme", "severe", "moderate", "minor", "unknown"
headline string Short alert summary
description string Full alert description
effective string ISO 8601 start time
expires string ISO 8601 expiry time
source string Issuing authority

When no alerts are active, the alerts array is empty ([]). Exit code is always 0 for a successful request, even when no alerts exist.

Plain output (TSV):

event	severity	headline	effective	expires	timestamp
Wind Advisory	moderate	Wind Advisory issued February 6 at 1:22PM EST until February 8 at 12:00AM EST by NWS Upton NY	2026-02-06T13:22:00-05:00	2026-02-07T05:00:00-05:00	2026-02-06T22:12:27.146277+00:00
Extreme Cold Warning	severe	Extreme Cold Warning issued February 6 at 1:22PM EST until February 8 at 1:00PM EST by NWS Upton NY	2026-02-06T13:22:00-05:00	2026-02-07T05:00:00-05:00	2026-02-06T22:12:27.146277+00:00

When no alerts are active, only the header row is printed:

event	severity	headline	effective	expires	timestamp

history

Get historical weather data. Returns hourly data points for past dates.

Syntax:

weather history <LOCATION> --date <YYYY-MM-DD>
weather history <LOCATION> --from <YYYY-MM-DD> --to <YYYY-MM-DD>
weather history --lat <LAT> --lon <LON> --date <YYYY-MM-DD>

Location inputs: city name, coordinates only. No ZIP or airport support.

Flags:

  • --date <YYYY-MM-DD> — Single date. Conflicts with --from/--to.
  • --from <YYYY-MM-DD> — Start of date range. Requires --to.
  • --to <YYYY-MM-DD> — End of date range. Requires --from.

Constraints:

  • Either --date or both --from and --to must be provided.
  • Dates must be on or after 1940-01-01.
  • Dates must be at least 5 days in the past (relative to current UTC date).
  • --from must not be after --to.

Example:

weather history "London" --date 2024-06-15 --json

JSON output (truncated — returns 24 hourly entries for a single date):

{
  "from": "2024-06-15",
  "hours": [
    {
      "conditions": "Partly cloudy",
      "humidity": 86.0,
      "precipitation": 0.0,
      "precipitation_probability": 0.0,
      "temperature": 11.2,
      "temperature_unit": "°C",
      "time": "2024-06-15T00:00:00+00:00",
      "wind_direction": 208.0,
      "wind_speed": 16.3,
      "wind_speed_unit": "km/h"
    },
    {
      "conditions": "Mainly clear",
      "humidity": 89.0,
      "precipitation": 0.0,
      "precipitation_probability": 0.0,
      "temperature": 10.6,
      "temperature_unit": "°C",
      "time": "2024-06-15T01:00:00+00:00",
      "wind_direction": 222.0,
      "wind_speed": 16.8,
      "wind_speed_unit": "km/h"
    }
  ],
  "location": {
    "country": "United Kingdom",
    "latitude": 51.50853,
    "longitude": -0.12574,
    "name": "London",
    "timezone": "Europe/London"
  },
  "provider": "Open-Meteo",
  "timestamp": "2026-02-06T22:12:32.797771+00:00",
  "to": "2024-06-15"
}

JSON schema (top level):

Field Type Description
from string Start date (YYYY-MM-DD)
to string End date (YYYY-MM-DD)
hours array Hourly data points (same element schema as forecast hourly)
location object Location details (see Location object schema under current)
provider string Provider name
timestamp string ISO 8601 request timestamp

Plain output (TSV, truncated — one row per hour):

time	temperature(°C)	conditions	precip_prob(%)	precipitation(mm)	wind_speed(km/h)	wind_dir	humidity(%)	timestamp
2024-06-15T00:00:00+00:00	11.2	Partly cloudy	0	0	16.3	208	86	2026-02-06T22:12:36.493888+00:00
2024-06-15T01:00:00+00:00	10.6	Mainly clear	0	0	16.8	222	89	2026-02-06T22:12:36.493888+00:00
2024-06-15T02:00:00+00:00	9.9	Partly cloudy	0	0	17.2	233	91	2026-02-06T22:12:36.493888+00:00

providers

List configured weather providers and their status.

weather providers --json

JSON output (array — no top-level timestamp):

[
  {
    "name": "openmeteo",
    "requires_key": false,
    "role": "primary",
    "status": "available"
  },
  {
    "name": "openweathermap",
    "requires_key": true,
    "role": "fallback",
    "status": "not_configured"
  }
]

JSON schema for each element:

Field Type Description
name string Provider identifier
role string "primary" or "fallback"
status string "available", "configured", or "not_configured"
requires_key boolean Whether an API key is needed

Note: The providers command returns a JSON array, not an object. No timestamp field is injected at the top level.

Plain output (TSV):

name	role	status	requires_key	timestamp
openmeteo	primary	available	false	2026-02-06T22:12:40.035632+00:00
openweathermap	fallback	not_configured	true	2026-02-06T22:12:40.035632+00:00

cache stats

Show location cache statistics.

weather cache stats --json

JSON output:

{
  "db_path": "/tmp/weather-cli-cache/locations.db",
  "db_size_bytes": 12288,
  "entries": 5,
  "timestamp": "2026-02-06T22:12:40.035632+00:00"
}

Note: The db_path value is system-dependent. On macOS it uses ~/Library/Caches/weather-cli/locations.db; on Linux it uses XDG cache conventions (defaults to ~/.cache/weather-cli/locations.db, respects XDG_CACHE_HOME). Override with WEATHER_CLI_CACHE_DIR.

JSON schema:

Field Type Description
db_path string Absolute path to the SQLite cache database
db_size_bytes integer Size of the database file in bytes
entries integer Number of cached location entries
timestamp string ISO 8601 timestamp of the query

Plain output (TSV):

entries	db_size_bytes	db_path	timestamp
5	12288	/tmp/weather-cli-cache/locations.db	2026-02-06T22:12:40.035632+00:00

cache clear

Clear the location cache.

weather cache clear --json

JSON output:

{
  "message": "Location cache cleared",
  "timestamp": "2026-02-06T22:12:58.752023+00:00"
}

JSON schema:

Field Type Description
message string Confirmation message
timestamp string ISO 8601 timestamp of the operation

Plain output (TSV):

message	timestamp
Location cache cleared	2026-02-06T22:12:58.752023+00:00

auth set

Set an API key for a weather provider.

Syntax:

weather auth set <PROVIDER_NAME> <API_KEY>

Arguments:

  • <PROVIDER_NAME> — Provider identifier (currently only openweathermap).
  • <API_KEY> — The API key value to store.

If the config file does not exist, auth set automatically runs init first.

Example:

weather auth set openweathermap "abc123def456" --json

JSON output:

{
  "config_path": "~/Library/Application Support/weather-cli/config.toml",
  "message": "API key set for openweathermap",
  "provider": "openweathermap",
  "timestamp": "2026-02-07T12:00:00+00:00"
}

JSON schema:

Field Type Description
message string Confirmation message
provider string Provider identifier
config_path string Absolute path to the config file
timestamp string ISO 8601 timestamp

Plain output (TSV):

message	provider	config_path	timestamp
API key set for openweathermap	openweathermap	~/Library/Application Support/weather-cli/config.toml	2026-02-07T12:00:00+00:00

auth remove

Remove (clear) an API key for a weather provider.

Syntax:

weather auth remove <PROVIDER_NAME>

Arguments:

  • <PROVIDER_NAME> — Provider identifier (currently only openweathermap).

Requires an existing config file. If none exists, returns CONFIG_ERROR with guidance to run weather init or weather auth set.

Example:

weather auth remove openweathermap --json

JSON output:

{
  "config_path": "~/Library/Application Support/weather-cli/config.toml",
  "message": "API key removed for openweathermap",
  "provider": "openweathermap",
  "timestamp": "2026-02-07T12:00:00+00:00"
}

JSON schema:

Field Type Description
message string Confirmation message
provider string Provider identifier
config_path string Absolute path to the config file
timestamp string ISO 8601 timestamp

Plain output (TSV):

message	provider	config_path	timestamp
API key removed for openweathermap	openweathermap	~/Library/Application Support/weather-cli/config.toml	2026-02-07T12:00:00+00:00

auth status

Show which providers have API keys configured, with masked key hints.

Syntax:

weather auth status

Requires an existing config file.

Example:

weather auth status --json

JSON output (key configured):

{
  "providers": [
    {
      "key_configured": true,
      "key_hint": "ab12****",
      "name": "openweathermap"
    }
  ],
  "timestamp": "2026-02-07T12:00:00+00:00"
}

JSON output (no key):

{
  "providers": [
    {
      "key_configured": false,
      "key_hint": "not set",
      "name": "openweathermap"
    }
  ],
  "timestamp": "2026-02-07T12:00:00+00:00"
}

JSON schema (top level):

Field Type Description
providers array Array of provider key status objects
timestamp string ISO 8601 timestamp

JSON schema for each element in providers array:

Field Type Description
name string Provider identifier
key_configured boolean Whether an API key is set
key_hint string Masked key (first 4 chars + "****") or "not set"

Plain output (TSV):

provider	key_configured	key_hint	timestamp
openweathermap	true	ab12****	2026-02-07T12:00:00+00:00

Agent guidance: When a user wants to use OpenWeatherMap, use weather auth status to check if a key is configured. If not, ask the user for their API key, then run weather auth set openweathermap "<key>" to save it. The key will persist across sessions.

Location Input

The current command supports all four location input methods. All other commands (forecast, alerts, history) support only city name and coordinates.

Method Syntax Example Supported Commands
City name <LOCATION> (positional) weather current "London" all
Coordinates --lat <LAT> --lon <LON> weather current --lat 51.5 --lon -0.12 all
ZIP code --zip <ZIP> [--country <CC>] weather current --zip 10001 current only
Airport IATA --airport <IATA> weather current --airport SFO current only

Rules:

  • --lat and --lon must both be provided together.
  • When both coordinates and a city name are given, coordinates take priority.
  • --zip accepts an optional --country <CC> (ISO 3166-1 alpha-2 code). If --country is omitted, no country filter is applied to the geocoding request; the API returns the best global match for the ZIP code.
  • Airport lookup is offline (embedded database) — no network call needed.
  • Resolved locations are cached in a local SQLite database for performance.

Global Flags

Flag Type Default Description
--json boolean true Output as JSON. This is the default format.
--plain boolean false Output as TSV (tab-separated values). Conflicts with --json.
--units <UNITS> enum metric Unit system. Values: metric, imperial, si.
-q, --quiet boolean false Suppress non-essential stderr messages (info/warnings).
--provider <PROVIDER> enum (from config) Force a specific provider. Values: openmeteo, openweathermap.
--version boolean — Print version number and exit.
-h, --help boolean — Print help text and exit.

Unit systems:

  • metric — Temperature: °C, Wind speed: km/h, Pressure: hPa
  • imperial — Temperature: °F, Wind speed: mph, Pressure: hPa
  • si — Temperature: °C, Wind speed: m/s, Pressure: hPa

Output Formats

JSON (default)

  • All JSON output is pretty-printed.
  • For responses that are JSON objects, a timestamp field (ISO 8601, UTC) is automatically injected if not already present in the data.
  • Responses that are JSON arrays (e.g., providers) do not receive an injected timestamp field.
  • Errors are written to stderr as a single-line JSON object.
  • Successful output is written to stdout.

Plain (TSV)

  • Tab-separated values with a header row.
  • A timestamp column is appended to every row.
  • Header labels include units where applicable (e.g., temperature(°C)).
  • Errors are written to stderr as Error: <message>.

Error Handling

JSON error format

Errors are written to stderr as JSON:

{"error":"no location provided. Use a city name, --lat/--lon, --zip, or --airport","code":"LOCATION_NOT_FOUND","timestamp":"2026-02-06T22:12:52.982885+00:00"}

Error schema:

Field Type Description
error string Human-readable error message
code string Machine-readable error code (see below)
timestamp string ISO 8601 timestamp

Plain error format

Error: no location provided. Use a city name, --lat/--lon, --zip, or --airport

Error codes

Code Exit Code Description
LOCATION_NOT_FOUND 1 Location could not be resolved
API_ERROR 1 Weather API returned an error
CONFIG_ERROR 1 Configuration issue (missing config, invalid values)
NETWORK_ERROR 1 Network request failed
NOT_IMPLEMENTED 2 Feature not yet available

Exit codes

  • 0 — Success
  • 1 — General error (location, API, config, network)
  • 2 — Not implemented

Configuration

Run weather init to create the config file. The config file location depends on the OS:

  • macOS: ~/Library/Application Support/weather-cli/config.toml
  • Linux: ~/.config/weather-cli/config.toml

Override with the WEATHER_CLI_CONFIG_DIR environment variable.

Default config.toml:

[general]
default_units = "metric"
default_format = "json"

[providers]
primary = "openmeteo"
fallback = "openweathermap"

[providers.openweathermap]
api_key = ""

[cache]
location_ttl_days = 30

Fields:

  • general.default_units — Default unit system when --units is not specified. Values: "metric", "imperial", "si".
  • general.default_format — Default output format. Values: "json", "plain".
  • providers.primary — Primary weather provider. Values: "openmeteo", "openweathermap".
  • providers.fallback — Fallback provider used when primary fails (network/API errors only).
  • providers.openweathermap.api_key — API key for OpenWeatherMap. Leave empty to disable OWM.
  • cache.location_ttl_days — How many days to cache geocoded locations.

Environment variables:

  • WEATHER_CLI_CONFIG_DIR — Override the config directory path.
  • WEATHER_CLI_CACHE_DIR — Override the cache directory path.

Usage Guidance

Use this decision tree to select the right command:

  1. "What is the weather right now?" → weather current <LOCATION>
  2. "Will it rain in the next few hours?" → weather forecast hourly <LOCATION> — check precipitation_probability fields
  3. "What will the weather be like this week?" → weather forecast daily <LOCATION>
  4. "Are there any severe weather warnings?" → weather alerts <LOCATION> (US locations only)
  5. "What was the weather on a past date?" → weather history <LOCATION> --date <YYYY-MM-DD>
  6. "What weather providers are configured?" → weather providers
  7. "Set up an API key for a provider" → weather auth set <PROVIDER> <API_KEY>
  8. "Which providers have API keys?" → weather auth status

Recommendations:

  • Before planning outdoor activities in the US, run weather alerts first to check for severe weather warnings.
  • For travel planning, use weather forecast daily to get an overview, then weather forecast hourly for specific time windows.
  • Use --units imperial for US audiences, --units metric for international.
  • Use --quiet in scripts to suppress informational messages on stderr.
  • Pipe JSON output to jq for field extraction: weather current "London" | jq '.temperature'
  • The providers command requires no network access and is useful for verifying configuration.
  • For non-US locations, alerts always returns an empty array — do not rely on it for international alert data.