ansiweather

Weather in terminal, with ANSI colors and Unicode symbols
Log | Files | Refs | README | LICENSE

README.md (5706B)


      1 ## Description
      2 
      3 AnsiWeather is a Shell script for displaying the current weather conditions
      4 in your terminal, with support for ANSI colors and Unicode symbols.
      5 
      6 ![AnsiWeather Screenshot][1]
      7 
      8 Weather data comes from the `OpenWeatherMap` free weather API.
      9 
     10 
     11 
     12 ## Requirements
     13 
     14 AnsiWeather requires the following dependencies:
     15 
     16 - A command to fetch HTTP data such as FTP, cURL or wget
     17 - [jq][2] (lightweight and flexible command-line JSON processor)
     18 - [bc][3] (arbitrary precision numeric processing language), for doing float
     19   arithmetic
     20 
     21 
     22 
     23 ## Installation
     24 
     25 After cloning the repository, simply invoke the script by typing:
     26 
     27 	./ansiweather
     28 
     29 AnsiWeather packages are available for:
     30 
     31 - [OpenBSD][4]
     32 - [NetBSD][5]
     33 - [FreeBSD][6]
     34 - [Debian][7]
     35 - [Ubuntu][8]
     36 - [Homebrew][9]
     37 
     38 
     39 
     40 ## Usage
     41 
     42 ### Synopsis
     43 
     44 	ansiweather [-l location] [-u system] [-f days] [-F] [-a value]
     45 	            [-s value] [-k key] [-i value] [-w value] [-h value]
     46 	            [-H value] [-p value] [-d value] [-v]
     47 
     48 ### Options
     49 
     50 	-l location
     51 	        Specify location.
     52 	
     53 	-u system
     54 	        Specify unit system to use ( metric or imperial ).
     55 	
     56 	-f days
     57 	        Toggle forecast mode for the specified number of upcoming days.
     58 	
     59 	-F      Toggle forecast mode for the next five days.
     60 	
     61 	-a value
     62 	        Toggle ANSI colors display ( true or false ).
     63 	
     64 	-s value
     65 	        Toggle symbols display ( true or false ).
     66 	
     67 	-k key  Specify OpenWeatherMap API key.
     68 	
     69 	-i value
     70 	        Toggle UV Index display ( true or false ).
     71 	
     72 	-w value
     73 	        Toggle wind data display ( true or false ).
     74 	
     75 	-h value
     76 	        Toggle humidity data display ( true or false ).
     77 	
     78 	-H value
     79 	        Toggle Feels like display ( true or false ).
     80 	
     81 	-p value
     82 	        Toggle pressure data display ( true or false ).
     83 	
     84 	-d value
     85 	        Toggle daylight data display ( true or false ).
     86 	
     87 	-v      Display version.
     88 
     89 ### Examples
     90 
     91 Display forecast using metric units for the next five days (showing symbols
     92 and daylight data) for Rzeszow, Poland:
     93 
     94 	ansiweather -l "Rzeszow,PL" -u metric -s true -f 5 -d true
     95 
     96 
     97 
     98 ## Configuration
     99 
    100 The default config file is ~/.ansiweatherrc. The environment variable
    101 ANSIWEATHERRC can be set to override this. The following configuration
    102 options (detailed below) are available and should be set according to
    103 your location and preferences.
    104 
    105 Example: `~/.ansiweatherrc`
    106 
    107 	location:Rzeszow,PL
    108 	fetch_cmd:ftp -V -o -
    109 	units:metric
    110 	show_daylight:true
    111 
    112 The file `ansiweatherrc.example` contains all available configuration
    113 variables.
    114 
    115 ### Location
    116 
    117 Location format is `city,CC` where `CC` is a two-letter ISO 3166-1 alpha-2
    118 country code. A list of country codes is available [here][10].
    119 Alternatively, it's also possible to specify locations by their ID, a city
    120 list is available [here][11].
    121 
    122 In case no location is specified, AnsiWeather will fallback to the default
    123 location.
    124 
    125 Example: `Rzeszow,PL`
    126 
    127 	location:Rzeszow,PL
    128 
    129 ### Fetch Command
    130 
    131 Various tools can be used to fetch data: `curl`, `wget`, `ftp`.
    132 
    133 Please note that `ftp` flags and options might differ among implementations
    134 and versions, and the example provided here is known to work only on OpenBSD
    135 and NetBSD.
    136 
    137 Example: `curl -sf`
    138 
    139 	fetch_cmd:curl -sf
    140 
    141 Example: `wget -qO-`
    142 
    143 	fetch_cmd:wget -qO-
    144 
    145 Example: `ftp -V -o -`
    146 
    147 	fetch_cmd:ftp -V -o -
    148 
    149 Default: `curl -sf`
    150 
    151 ### System of Units
    152 
    153 Both `metric` and `imperial` systems are supported.
    154 
    155 	units:metric
    156 
    157 Default: `metric`
    158 
    159 ### Display ANSI sequences
    160 
    161 Toggle ANSI sequences display. Value can be either `true` (requires an ANSI
    162 capable display) or `false`.
    163 
    164 	ansi:true
    165 
    166 Default: `true`
    167 
    168 ### Display symbols
    169 
    170 Toggle Unicode symbols display. Value can be either `true` (requires a
    171 Unicode capable display) or `false`.
    172 
    173 	symbols:true
    174 
    175 Default: `false`
    176 
    177 Symbols can be configured or replaced by custom text using the following
    178 configuration variables: `sun`, `moon`, `clouds`, `rain`, `fog`, `mist`,
    179 `haze`, `snow`, `thunderstorm`.
    180 
    181 ### Display forecast
    182 
    183 Show upcoming forecast for the next `N` days (for 0 <= N <= 7). `0` will
    184 show standard output.
    185 
    186 	forecast:5
    187 
    188 Default: `0`
    189 
    190 ### Display wind / humidity / pressure
    191 
    192 Toggle UV Index, wind, humidity, and/or pressure display. Values can be either
    193 `true` or `false`.
    194 
    195 	show_uvi:true
    196 	show_wind:true
    197 	show_humidity:true
    198 	show_pressure:true
    199 
    200 Default: `true`
    201 
    202 ### Display sunrise / sunset
    203 
    204 Toggle daylight display. Value can be either `true` or `false`.
    205 
    206 	show_daylight:false
    207 
    208 Default: `false`
    209 
    210 ### Date and Time format
    211 
    212 Configure date and time format display. See Unix date formatting docs
    213 for details.
    214 
    215 	dateformat:%a %b %d
    216 
    217 Default: `%a %b %d`
    218 
    219 	timeformat:%b %d %r
    220 
    221 Default: `%b %d %r`
    222 
    223 ### OpenWeatherMap API key
    224 
    225 Specify an OpenWeatherMap API key. By default AnsiWeather uses its own
    226 key, but users can optionally get their own one by creating a free
    227 [OpenWeatherMap account][12].
    228 
    229 	api_key:85a4e3c55b73909f42c6a23ec35b7147
    230 
    231 
    232 
    233 ## License
    234 
    235 AnsiWeather is released under the BSD 2-Clause license. See `LICENSE` file
    236 for details.
    237 
    238 
    239 
    240 ## Author
    241 
    242 AnsiWeather is developed by Frederic Cambus.
    243 
    244 - Site: https://www.cambus.net
    245 
    246 
    247 
    248 ## Resources
    249 
    250 GitHub: https://github.com/fcambus/ansiweather
    251 
    252 [1]: https://www.cambus.net/files/ansiweather/ansiweather.png
    253 [2]: https://stedolan.github.io/jq/
    254 [3]: https://www.gnu.org/software/bc/
    255 [4]: https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/astro/ansiweather
    256 [5]: https://pkgsrc.se/misc/ansiweather
    257 [6]: https://www.freshports.org/misc/ansiweather
    258 [7]: https://packages.debian.org/search?keywords=ansiweather
    259 [8]: https://packages.ubuntu.com/search?keywords=ansiweather
    260 [9]: https://formulae.brew.sh/formula/ansiweather
    261 [10]: https://www.statdns.com/cctlds/
    262 [11]: https://bulk.openweathermap.org/sample/
    263 [12]: https://home.openweathermap.org/users/sign_up