NAME¶
weather - command-line tool to obtain weather conditions and forecasts
SYNOPSIS¶
weather [
options ] [
alias1 |
search1 [
alias2 |
search2 [...]]]
DESCRIPTION¶
This command-line utility is intended to provide quick access to current weather
conditions and forecasts. Presently, it is capable of returning data for
localities throughout the USA and some select locations globally by retrieving
and formatting decoded METARs (Meteorological Aerodrome Reports) from NOAA
(the USA National Oceanic and Atmospheric Administration) and forecasts/alerts
from NWS (the USA National Weather Service). The tool is written to function
in the same spirit as other command-line informational utilities like
cal(1),
calendar(1) and
dict(1). It retrieves arbitrary
weather data via precompiled correlations or custom-tailored aliases
(system-wide or on a per-user basis).
Behavior can be determined by command-line options and specification of zero or
more location aliases and search terms.
Aliases are defined in
weatherrc(5) files, as a convenient means of
grouping URIs together using a short name. Specifying multiple aliases or
location search terms on the command line causes the utility to output data
for each, as if it had been invoked multiple times. If none are specified,
then an alias of
default is checked for a
defargs option and any
alias names listed within it (comma-separated) are applied instead.
Searches utilize location correlation sets in INI-style text files named
airports,
places,
stations,
zctas and
zones. A precomputed copy is distributed with the source, but can be
rebuilt from updated data sources as needed by placing them in the current
working directory and running with the
--build-sets option (see the
comments at the top of any location correlation set file for instructions on
where to find updated data sources). Positive search results are cached and
sourced as aliases on subsequent runs for as long as the correlation sets
remain unchanged, and are cleared automatically once the correlation sets are
updated.
Retrieved data is also cached automatically for a short period of time,
adjustable with the
cacheage configuration option or
--cacheage
command-line option. This helps throttle load against NOAA/NWS servers in case
the utility is repeatedly re-run requesting the same data, but can be
overridden with the
cache_data configuration option or
--no-cache-data command-line option.
OPTIONS¶
A summary of options is included below.
- --version
- show program's version number and exit
- -h, --help
- show a help message and exit
- -a, --alert
- include local alert notices
- --atypes=ATYPES
- list of alert notification types to display (ex:
tornado_warning,urgent_weather_message)
- --build-sets
- (re)build location correlation sets
- --cacheage=CACHEAGE
- duration in seconds to refresh cached data (ex: 900)
- --cachedir=CACHEDIR
- directory for storing cached searches and data (ex:
~/.weather)
- -f, --forecast
- include a local forecast
- --headers=HEADERS
- list of conditions headers to display (ex: temperature,wind)
- --imperial
- filter/convert conditions for US/UK units
- --info
- output detailed information for your search
- -l, --list
- list all configured aliases and cached searches
- --longlist
- display details of all configured aliases
- -m, --metric
- filter/convert conditions for metric units
- -n, --no-conditions
- disable output of current conditions
- --no-cache
- disable all caching (searches and data)
- --no-cache-data
- disable retrieved data caching
- --no-cache-search
- disable search result caching
- -q, --quiet
- skip preambles and don't indent
- --setpath=SETPATH
- directory search path for correlation sets (ex: .:~/.weather)
- -v, --verbose
- show full decoded feeds
EXAMPLES¶
- weather
- View output for the default alias, if one has been defined (otherwise
display usage/syntax similar to --help)
- weather rdu
- Display weather conditions at the airport with IATA/FAA code
RDU.
- weather --info raleigh
- Show a list of FIPS codes for United States Census Bureau places
containing the word raleigh (or the proximity information if only
one match was found).
- weather "^ral[ie]{2}gh
city.*nc$"
- Get the current weather conditions from the nearest station to the Census
place name matching the regular expression provided.
- weather -fv fips3755000
- Get the full decoded METAR from the nearest station, and the forecast data
for the nearest zone to the Census place with FIPS code 3755000
with no special filtering or formatting.
- weather --forecast --no-cache-data 27613
- Ignore any recent cached METAR or forecast data and display fresh output
for the nearest station and zone to the Census ZCTA (essentially USPS ZIP
code) 27613.
- weather home work
- Show current conditions for both the home and work aliases
in that order.
- weather 35.878573,-78.727813
- weather 35-52-43n,78-43-40w
- weather "35-52n, 78-43w"
- Display weather conditions for the nearest station to an arbitrary set of
global coordinates in latitude,longitude order either in decimal format or
degree, degree-minute or degree-minute-second formats, optionally using
signed or cardinal hemisphere designations with or without spacing. Note
that the cut-off for maximum acceptable distance is hard-coded at 0.1
radians (roughly 637km or 396mi).
weather may additionally obtain configuration data from a system-wide
configuration file, a per-user configuration file, and a local directory
configuration file. The file format and configuration options are described in
weatherrc(5). They are aggregated in the following order:
- /etc/weatherrc
- the system-wide configuration
- ~/.weather/weatherrc or ~/.weatherrc
- the per-user configuration
- ./weatherrc
- the local directory configuration
AUTHOR¶
Utility and manual written by Jeremy Stanley <fungi@yuggoth.org>.
SEE ALSO¶
weatherrc(5)