ansiweather

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

README.md (5578B)


      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 [-F] [-l location] [-u system] [-f days] [-a value]
     45 	            [-s value] [-k key] [-i value] [-w value] [-h value]
     46 	            [-p value] [-d value] [-v value]
     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 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 	-p value
     79 	        Toggle pressure data display ( true or false )
     80 	
     81 	-d value
     82 	        Toggle daylight data display ( true or false )
     83 
     84 ### Examples
     85 
     86 Display forecast using metric units for the next five days (showing symbols
     87 and daylight data) for Rzeszow, Poland:
     88 
     89 	ansiweather -l Rzeszow,PL -u metric -s true -f 5 -d true
     90 
     91 
     92 
     93 ## Configuration
     94 
     95 The default config file is ~/.ansiweatherrc. The environment variable
     96 ANSIWEATHERRC can be set to override this. The following configuration
     97 options (detailed below) are available and should be set according to
     98 your location and preferences.
     99 
    100 Example: `~/.ansiweatherrc`
    101 
    102 	location:Rzeszow,PL
    103 	fetch_cmd:ftp -V -o -
    104 	units:metric
    105 	show_daylight:true
    106 
    107 The file `ansiweatherrc.example` contains all available configuration
    108 variables.
    109 
    110 ### Location
    111 
    112 Location format is `city,CC` where `CC` is a two-letter ISO 3166-1 alpha-2
    113 country code. A list of country codes is available [here][10].
    114 Alternatively, it's also possible to specify locations by their ID, a city
    115 list is available [here][11].
    116 
    117 In case no location is specified, AnsiWeather will fallback to the default
    118 location.
    119 
    120 Example: `Rzeszow,PL`
    121 
    122 	location:Rzeszow,PL
    123 
    124 ### Fetch Command
    125 
    126 Various tools can be used to fetch data: `curl`, `wget`, `ftp`.
    127 
    128 Please note that `ftp` flags and options might differ among implementations
    129 and versions, and the example provided here is known to work only on OpenBSD
    130 and NetBSD.
    131 
    132 Example: `curl -sf`
    133 
    134 	fetch_cmd:curl -sf
    135 
    136 Example: `wget -qO-`
    137 
    138 	fetch_cmd:wget -qO-
    139 
    140 Example: `ftp -V -o -`
    141 
    142 	fetch_cmd:ftp -V -o -
    143 
    144 Default: `curl -sf`
    145 
    146 ### System of Units
    147 
    148 Both `metric` and `imperial` systems are supported.
    149 
    150 	units:metric
    151 
    152 Default: `metric`
    153 
    154 ### Display ANSI sequences
    155 
    156 Toggle ANSI sequences display. Value can be either `true` (requires an ANSI
    157 capable display) or `false`.
    158 
    159 	ansi:true
    160 
    161 Default: `true`
    162 
    163 ### Display symbols
    164 
    165 Toggle Unicode symbols display. Value can be either `true` (requires a
    166 Unicode capable display) or `false`.
    167 
    168 	symbols:true
    169 
    170 Default: `false`
    171 
    172 Symbols can be configured or replaced by custom text using the following
    173 configuration variables: `sun`, `moon`, `clouds`, `rain`, `fog`, `mist`,
    174 `haze`, `snow`, `thunderstorm`.
    175 
    176 ### Display forecast
    177 
    178 Show upcoming forecast for the next `N` days (for 0 <= N <= 7). `0` will
    179 show standard output.
    180 
    181 	forecast:5
    182 
    183 Default: `0`
    184 
    185 ### Display wind / humidity / pressure
    186 
    187 Toggle UV Index, wind, humidity, and/or pressure display. Values can be either
    188 `true` or `false`.
    189 
    190 	show_uvi:true
    191 	show_wind:true
    192 	show_humidity:true
    193 	show_pressure:true
    194 
    195 Default: `true`
    196 
    197 ### Display sunrise / sunset
    198 
    199 Toggle daylight display. Value can be either `true` or `false`.
    200 
    201 	show_daylight:false
    202 
    203 Default: `false`
    204 
    205 ### Date and Time format
    206 
    207 Configure date and time format display. See Unix date formatting docs
    208 for details.
    209 
    210 	dateformat:%a %b %d
    211 
    212 Default: `%a %b %d`
    213 
    214 	timeformat:%b %d %r
    215 
    216 Default: `%b %d %r`
    217 
    218 ### OpenWeatherMap API key
    219 
    220 Specify an OpenWeatherMap API key. By default AnsiWeather uses its own
    221 key, but users can optionally get their own one by creating a free
    222 [OpenWeatherMap account][12].
    223 
    224 	api_key:85a4e3c55b73909f42c6a23ec35b7147
    225 
    226 
    227 
    228 ## License
    229 
    230 AnsiWeather is released under the BSD 2-Clause license. See `LICENSE` file
    231 for details.
    232 
    233 
    234 
    235 ## Author
    236 
    237 AnsiWeather is developed by Frederic Cambus.
    238 
    239 - Site: https://www.cambus.net
    240 
    241 
    242 
    243 ## Resources
    244 
    245 GitHub: https://github.com/fcambus/ansiweather
    246 
    247 [1]: https://www.cambus.net/files/ansiweather/ansiweather.png
    248 [2]: https://stedolan.github.io/jq/
    249 [3]: https://www.gnu.org/software/bc/
    250 [4]: https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/astro/ansiweather
    251 [5]: https://pkgsrc.se/misc/ansiweather
    252 [6]: https://www.freshports.org/misc/ansiweather
    253 [7]: https://packages.debian.org/search?keywords=ansiweather
    254 [8]: https://packages.ubuntu.com/search?keywords=ansiweather
    255 [9]: https://formulae.brew.sh/formula/ansiweather
    256 [10]: https://www.statdns.com/cctlds/
    257 [11]: https://bulk.openweathermap.org/sample/
    258 [12]: https://home.openweathermap.org/users/sign_up