AnsiWeather: a shell script that fetches, parses, and prints weather

Three dependencies and one script

AnsiWeather is a shell script for displaying current weather in the terminal, with ANSI colors and Unicode symbols. Weather data comes from the OpenWeatherMap free weather API.

The dependency list is short enough to check in a second: a command to fetch HTTP data such as FTP, cURL or wget, jq as a lightweight and flexible command-line JSON processor, and bc for arbitrary precision numeric processing, described as being there for float arithmetic.

That last dependency is the one people miss. bc is not installed by default on many systems, and AnsiWeather uses it rather than shell arithmetic, which means the script is doing floating point maths rather than integer maths with a rounding error you have to think about.

Installation is running it from a clone:

./ansiweather

More usefully, packages exist for OpenBSD, NetBSD, FreeBSD, Debian, Ubuntu, Homebrew, Haiku, and Gentoo. That is an unusually broad packaging footprint for a shell script and is the strongest practical argument for using it: your distribution already carries a maintained copy.

The repository itself is correspondingly small. `ansiweather` is the script, `ansiweather.1` is the man page, `ansiweatherrc.example` holds every configuration variable, `ansiweather.plugin.zsh` is also included, and there are `ChangeLog`, `AUTHORS`, and `LICENSE` files.

The synopsis, and what each toggle controls

The command line is a set of short flags:

ansiweather [-l location] [-u system] [-f days] [-F] [-a value]
            [-s value] [-k key] [-i value] [-w value] [-h value]
            [-H value] [-p value] [-d value] [-v]

Location is `-l`, unit system is `-u` with `metric` or `imperial`, forecast is `-f` for a number of days, and `-F` is a shortcut for the next five days. `-k` takes the OpenWeatherMap API key and `-v` displays the version.

The rest are display toggles that all take `true` or `false`. `-a` for ANSI colors, `-s` for Unicode symbols, `-i` for the UV index, `-w` for wind, `-h` for humidity, `-H` for the feels-like reading, `-p` for pressure, and `-d` for daylight data.

Having a separate flag for every field rather than a verbosity level is the design decision that makes this script fit into a prompt. Most weather tools give you everything or a short and long form; this one lets you say exactly which numbers you want, which is what you need when the output is going into a status bar beside other information.

One documented nuance: the UV Index represents a single daily value rather than the UV index at the current time, so it is not the number you would read off a weather app mid-afternoon.

Configuration is four files, searched in order

Configuration is loaded from four locations, in this order:

1. The file specified by the `ANSIWEATHERRC` environment variable, if set. 2. `$XDG_CONFIG_HOME/ansiweather/config` 3. `~/.config/ansiweather/config` 4. `~/.ansiweatherrc`

The `ANSIWEATHERRC` variable is the one to use in scripts and for testing a different configuration without touching your real one.

The file format is one `key:value` pair per line, no spaces around the colon:

location:Rzeszow,PL
fetch_cmd:ftp -V -o -
units:metric
show_daylight:true

Every configuration key mirrors a command line flag, which means anything you can set once you can set temporarily, and vice versa. The README notes that `ansiweatherrc.example` contains all available configuration variables, so that file is the complete reference.

Two formatting keys are worth calling out because they are Unix date format strings. `dateformat` controls the date on forecast entries and defaults to `%a %b %d`. `timeformat` controls sunrise and sunset times and defaults to `%b %d %r`. If you want 24-hour times in the sunrise and sunset lines, that is where you change it.

Location, fetch command, and the API key

Location takes the form `city,CC`, where CC is a two-letter ISO 3166-1 alpha-2 country code, so `Rzeszow,PL`. A city can also be given by its OpenWeatherMap ID, with a list available from OpenWeatherMap's bulk sample file. If no location is specified, AnsiWeather falls back to the default location from the configuration.

The fetch command is configurable, and three examples are given: `curl -sf` as the default, `wget -qO-`, and `ftp -V -o -`. The README includes a specific warning about the third: ftp flags and options might differ among implementations and versions, and the example provided is known to work only on OpenBSD and NetBSD.

The documented ftp example is explicitly platform-bound.

The API key has a default, because AnsiWeather ships with its own OpenWeatherMap key and users only need their own if they want one. It is set as `api_key:` in the config, and the README links to the OpenWeatherMap free account sign-up. Worth knowing that the shared default means requests from every user of the script land on the same account, which is not something you control and not something you should rely on at any volume.

Symbols are configurable text, not fixed glyphs

Symbol display is off by default and requires a Unicode capable display. ANSI colors are on by default and require an ANSI capable display. Those two defaults are different, which is slightly surprising: you get colored output out of the box but not the weather glyphs.

The interesting part is that symbols are not hardcoded. Nine configuration variables can each be set or replaced by custom text: `sun`, `moon`, `clouds`, `rain`, `fog`, `mist`, `haze`, `snow`, and `thunderstorm`.

That means the glyph set is a configuration surface rather than a rendering detail. On a terminal with a limited font you can replace an unsupported glyph with a word, and on one with good coverage you can use whatever the font offers. It also means a screenshot in a README is not necessarily what you will see.

The forecast setting is `forecast:N`, where N runs from 0 to 7, and 0 shows standard output. The setting is limited to seven days, so AnsiWeather is not a tool for looking two weeks ahead.

Where this fits among terminal weather tools

The alternative approaches split cleanly into three groups.

A dedicated weather client with its own binary is the closest comparison: same data source, similar output, but a program to install and keep updated rather than a script you read. The difference that matters in practice is where the configuration lives and how you extend it, and a script you can read in full wins that comparison outright.

Curl plus jq, written inline in your own script, is the second option and a serious one. For a status bar where you want exactly two fields, a two-line pipeline beats adding a dependency, and the README itself hands you the pieces: the API URL structure is not in the documentation, but the fetch command and the JSON parsing are, so assembling it yourself is a short exercise.

A general-purpose system information tool with a weather module is the third, and it is the awkward fit. Those tools tend to want configuration in their own format, output designed to align with columns, and a plugin architecture that a single shell script cannot participate in.

What AnsiWeather has that a pipeline does not is the option surface: unit systems, forecast up to seven days, per-field toggles, custom date and time formats, and replaceable symbols. That is enough to put it in a prompt permanently rather than run it occasionally.

Licence, authorship, and the release rhythm

AnsiWeather is released under the BSD 2-Clause licence, documented in the `LICENSE` file.

It is developed by Frederic Cambus, whose site is listed in the README, and the BSD family is not incidental to the packaging: OpenBSD, NetBSD, and FreeBSD ports are listed alongside the Linux distributions, Homebrew, and Haiku.

The release rhythm has slowed. Version 1.19.0 is dated 2023-01-09, version 1.18.0 is dated 2021-09-14, and version 1.19.1 is dated 2026-07-24, which is also the date of the last push. So the most recent patch followed a multi-year release gap.

That is worth weighing against the fact that this tool's upstream is an external API whose response format could change at any time. If OpenWeatherMap alters its JSON, a shell script with one maintainer and a three-year gap between releases is the thing that breaks, and there is no test suite in the repository to catch it.

The counterargument is that there is almost nothing to break. The script has no state, no build step, and a man page and example configuration that document its entire surface, and you can read the whole thing before running it.

Editorial conclusion

Adopt AnsiWeather if you want weather in a terminal prompt or status bar and are content to depend on OpenWeatherMap's free API, since the whole tool is one script with no runtime to install. Do not adopt it for anything that needs reliability guarantees, because it depends on a third-party API key and has had multi-year gaps between tagged releases. Verify first that your fetch_cmd works on your platform, since the documented ftp example is stated to be known to work only on OpenBSD and NetBSD.

Frequently asked questions

Official sources

1. fcambus/ansiweather on GitHub
2. Issues
3. License: BSD-2-Clause
4. README
5. Releases