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:

Weather CLI commands

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:

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:

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

Weather CLI

Recommended for

Weather CLI commands

weather — Weather CLI for Agents and Scripting

Installation

Quick Reference

Commands

`init`

`current`

`forecast hourly`

`forecast daily`

`alerts`

`history`

`providers`

`cache stats`

`cache clear`

`auth set`

`auth remove`

`auth status`

Location Input

Global Flags

Output Formats

JSON (default)

Plain (TSV)

Error Handling

JSON error format

Plain error format

Error codes

Exit codes

Configuration

Usage Guidance

Prompt Engineering

Data Visualization

RAG Architecture Setup