Skip to content
A minimal, flexible command-line tool for displaying the current weather in your location, optimized for your terminal prompt.
JavaScript Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Terminal weather is a minimal, flexible command-line tool for displaying the current weather in your location, optimized for rapid re-rendering in your terminal prompt.




  • Run npm install -g terminal-weather
  • Run terminal-weather configure to set it up. You will be prompted for your open API key as well the default temperature unit.

Which Services It Uses

Terminal-weather uses the following APIs:

Caching and Module loading

  • terminal-weather adheres to's limit of 1 http call per ten-minute interval. The rest of the time it prints a cached value.
  • terminal-weather loads in a progressive way. Because the most frequent case is retrieving cached data, only the modules required for that are loaded. In case of a cache expiration, the additional modules required to retreive new weather data are loaded. The point is to maintain a seamless terminal experience when embedding terminal-weather in your prompt (see below).



    Usage: terminal-weather
       or: terminal-weather [options],                  ex: terminal-weather -p 
       or: terminal-weather configure,                  ex: terminal-weather configure
       or: terminal-weather show (display | config),    ex: terminal-weather show display
       or: terminal-weather uninstall,                  ex: terminal-weather uninstall 

        -h, --help                                      print this usage page
        -n, --no-cache                                  invalidate cache before printing weather string  
        -p, --prompt                                    print weather string with no trailing new line. Useful for embedding in your terminal prompt.
        -d, --display=DISPLAY_MODE                      get or set display mode.
        -f, --format=FORMAT_STRING                      get or set the format string determining the weather string output.
        -u, --units=UNIT_TYPE                           get or set temp unit type.


If you update your display, units and/or format string, the update will not be visible until the cache expires. To make the effects immediately visible, pass the -n flag to explicitly invalidate the cache at the same time. E.g.:

terminal-weather -n --display=icon
terminal-weather -nd=icon 

Controlling the Output

To configure the order of terminal-weather's information, pass a string of characters from the list below to the format command.

T: Temperature

D: Display

The default format string is 'T D ', which renders something like '73° F clouds ', assuming that your display setting is text. The format string is space-sensitive, so you can control the spacing how you want.

Example: $ terminal-weather format 'D T '.

Note: the following weather information is forthcoming for the api:

H: Humidity

P: Atmospheric Pressure

R: Range (hi/lo)


  • Run terminal-weather configure and give terminal-weather the values it needs to store so it can continually query the api.
  • This configuration file is stored in the application's root directory (run terminal-weather show config to see the location of this file).

Getting terminal-weather into your terminal prompt

If you want to include terminal-weather in your bash prompt, there are a couple things you need to do:

  1. Make sure that /usr/local/bin is in your $PATH so that your shell can locate it. If after installing terminal weather, you can't run terminal-weather from your terminal, you may have not installed it globally (using the -g flag).

  2. Add the following lines to your ~/.bashrc file:

     # a function to insert the terminal-weather bash fn inside the PS1 variable
     set_bash_prompt() {
         PS1="$(terminal-weather -p)\u@[\h]$ $(history -n)"
     # include above fn in prompt command variable so the prompt is reset each time it is rendered
     PROMPT_COMMAND="set_bash_prompt; $PROMPT_COMMAND"

Known Issues

Terminal weather's responsiveness seems to degrade if you source your ~/.bashrc multiple times from within a shell. Try running exec $SHELL -l.

Removing terminal-weather

  • First (definitely do this first!!!), remove terminal weather call from the bash prompt in your ~/.bashrc file
  • run terminal-weather uninstall. This is equivalent to running npm uninstall -g terminal-weather.
You can’t perform that action at this time.