# wego: a terminal weather client with pluggable backends and frontends

> wego is a Go-based weather command-line tool that fetches forecasts from multiple backends (OpenWeatherMap, WeatherAPI, Open-Meteo, and others) and displays them in your choice of ASCII, emoji, markdown or JSON. It runs offline with cached data and requires only a terminal.

**schachmat/wego** — weather app for the terminal

- Repository: https://github.com/schachmat/wego
- Stars: 8,559 · Forks: 506
- Language: Go
- License: ISC
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/schachmat-wego

## A weather tool built for the terminal

wego is a command-line weather client written in Go. It fetches forecasts from multiple weather data providers and displays them in your terminal with wind, precipitation, humidity, and temperature information. The tool is composable; you can pipe JSON output from one wego invocation into another, or feed weather data from a local JSON file into the display frontends for offline use. Temperature display includes both measured and felt (wind chill) values, with forecasts for 1 to 7 days. Configuration is stored in a simple text file; the tool auto-generates this file on first run, prompting you to choose a backend and location. Last push was on 2026-09-26, three days ago. The project is licensed under ISC, a permissive open source license similar to MIT.

## Multiple backends, multiple frontends

wego separates data fetching from display. On the backend side, you choose where weather data comes from. Open-Meteo is free and requires no API key, making it the simplest choice for experimenting. SMHI is also free and keyless but covers only Sweden and surrounding areas. OpenWeatherMap and WeatherAPI require free API keys that you sign up for online. Caiyun targets China with API-key authentication and supports Chinese. Pirateweather offers a free tier but requires latitude and longitude for location; you cannot pass a city name to it. Worldweatheronline no longer provides free keys. You can also read from a local JSON file, useful for testing or offline display.

On the frontend side, you choose how to render the data. The ascii-art-table frontend is the default, displaying a colored table with weather symbols. The emoji frontend is more compact. Markdown produces a markdown table. JSON outputs raw forecast data, suitable for piping to other tools or scripts. For example, `wego --frontend emoji London` displays the forecast as emoji icons. Both ascii-art-table and emoji frontends can display temperatures and wind speeds in color; the markdown and json frontends strip formatting.

## Installation and first forecast

Install wego via Go's built-in package manager:

```bash
go install github.com/schachmat/wego@latest
```

You need Go 1.20 or later. Some Linux distributions package wego; check your repository first. On first run, wego will fail but will create a config file:

```bash
wego
```

This command generates a config file at `$XDG_CONFIG_HOME/wego/wegorc` (typically `~/.config/wego/wegorc` on Linux). Edit the config file and choose a backend. For a free start, set:

```
backend=openmeteo
location=New York
```

Save the file and run wego again:

```bash
wego
```

You will see a colored forecast. To get a forecast for a different location, pass it on the command line: `wego London` or `wego Paris 4` (for 4 days). The argument order does not matter. The config file also accepts a default number of days via the `days` option. Multi-language output is supported through language configuration in the wegorc file, though the README does not document which language codes are available.

## Config file locations and environment variables

wego checks for a config file in this order: first, the path in the `$WEGORC` environment variable if set; second, the XDG config directory (`$XDG_CONFIG_HOME/wego/wegorc`, defaulting to `~/.config/wego/wegorc` on Linux and the OS equivalent on macOS and Windows via `os.UserConfigDir()`); third, the legacy `~/.wegorc` location for backward compatibility. If none exist, wego creates the file at the XDG location. This design lets you override the config with an environment variable for testing or one-off runs without editing the file. The wegorc file also supports a `frontend` option to change the default display format, a `units` option to choose metric, imperial, si, or metric-ms, and language preferences with keys like `en-lang`, though specific supported languages are not documented in the README. The `--cache-ttl` flag controls how long cached weather data remains valid before a fresh fetch is required.

## Display options and terminal requirements

Both ascii-art-table and emoji frontends display temperatures and wind speeds in color by default. To disable colors, pass the `--monochrome` flag or add `monochrome=true` to the config file. You can also set the `NO_COLOR` environment variable (see [no-color.org](https://no-color.org/)) to disable colors globally without touching the config:

```bash
NO_COLOR=1 wego
```

The ascii-art-table and emoji frontends require a UTF-8 terminal with 256 color support and a monospaced font that includes all the weather symbols. dejavu sans mono is one example. If your terminal does not meet these requirements, use the markdown or json frontends instead. Terminals limited to 16 colors will not render the temperature and wind speed coloring correctly, making the markdown or json output a better choice. The emoji frontend displays a more compact forecast, while ascii-art-table produces a wider table suitable for large displays.

## Caching and offline use

wego caches weather data to disk with a configurable time-to-live. The `--cache-ttl` flag controls how long cached data remains valid. This caching means that after fetching a forecast once, you can run wego again without making a new API request until the cache expires. For offline work or testing, the json backend lets you point wego at a local JSON file instead of fetching from a remote API. For example, set `backend=json` and `location=/path/to/weather.json`. This backend reads the JSON structure and pipes it directly to the chosen frontend, allowing weather pipelines. The cache system reduces API quota usage and speeds up repeated queries from the same location. The caching directory location is not documented in the README.

## Built-in documentation and composability

wego includes a built-in man page. Run `wego --man` to read the full manual without leaving the terminal. The tool also supports multi-language output via the config file options like `en-lang`, though specific language codes are not documented in the README. The composable JSON mode is a distinctive feature: you can pipe the json backend output to the json frontend, or to other tools, building weather pipelines. Unit systems can be set to metric, imperial, si, or metric-ms in the config file. The si system uses Kelvin for temperature. The metric-ms system uses meters per second for wind speed instead of kilometers per hour. The project repository includes a backends/ directory and a frontends/ directory, separating backend implementations from display logic. The iface/ directory holds interface definitions. Automatic config management uses the ingo library to handle file I/O and config resolution.

## Dependencies and supported platforms

wego requires Go 1.20 or later to build from source. The tool depends on the go-colorable library for color output, go-runewidth for handling multi-width characters in Unicode, the muesli/mango and muesli/roff libraries for man page generation, the ingo library for config file handling, and smaller packages for platform-specific functionality. The README does not document which operating systems are officially supported, but the use of `os.UserConfigDir()` suggests support for Linux, macOS, and Windows. The UTF-8 terminal requirement and 256-color support limit usage to modern terminal emulators. The backend dependencies themselves (OpenWeatherMap, WeatherAPI, etc.) impose their own API rate limits; the README does not document what these limits are or how to monitor usage. For Worldweatheronline, the README notes in a GitHub issue reference that free API keys are no longer available.

## Conclusion

Adopt wego if you spend your day in the terminal and want weather forecasts without leaving it, or if you need to pipe weather data into scripts. Open-Meteo and SMHI are free and keyless, suiting privacy-conscious users. Skip wego if you prefer graphical weather apps or if you need mobile access. Verify that your terminal has 256 colors and a monospaced font that includes the weather symbols the ascii-art-table and emoji frontends need.

## FAQ

### How do I install wego?

Install via Go with go install github.com/schachmat/wego@latest (requires Go 1.20+), or check your Linux distribution's package manager.

### Which weather backends are free and do not require an API key?

Open-Meteo is free and requires no API key and works worldwide. SMHI is also free and keyless but only covers Sweden and surrounding areas.

### How do I change the weather display format from ASCII art to emoji?

Pass --frontend emoji on the command line, or add frontend=emoji to your wegorc config file.

### Can I use wego offline?

Yes, wego caches weather data to disk; once fetched, you can view cached forecasts without an internet connection. You can also use the json backend to point wego at a local JSON file.

### What unit systems does wego support?

wego supports metric, imperial, si (Kelvin for temperature), and metric-ms (meters per second for wind speed). Set the units option in the wegorc config file or pass it via command line.

## Sources

- [Issues](https://github.com/schachmat/wego/issues)
- [License: ISC](https://github.com/schachmat/wego/blob/master/LICENSE)
- [README](https://github.com/schachmat/wego/blob/master/README.md)
- [Releases](https://github.com/schachmat/wego/releases)
- [schachmat/wego on GitHub](https://github.com/schachmat/wego)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/schachmat-wego