WeatherCLISample

A Node.js + TypeScript CLI that fetches real weather and renders it as plain-ASCII art — sun rays, rain drops, snowflakes — right in your terminal. No browser, no app, no subscription.

Why WeatherCLISample?

• Instant. One command, weather in under two seconds.
• Readable anywhere. Plain ASCII art, no Unicode, no emoji — works on every terminal, SSH session, and legacy font.
• Smart radius mode. --max-hours 3 scans every city within a driving radius and prints the one with the best weather score.
• Machine-friendly. --json emits a typed JSON payload ready for scripts, dashboards, and pipes.
• Honest about its limits. Scoring weights and driving-time approximations are documented up front, not hidden.

Quick Start

npm install -g @bitmia/weather-cli-sample
weather-cli-sample --city Barcelona

No configuration required. On first run WeatherCLISample auto-detects your location via IP geolocation and prints your local weather.

Install

Global (recommended)

npm install -g @bitmia/weather-cli-sample
weather-cli-sample --help

Build from source

git clone https://github.com/Bitmia-ai/WeatherCLI-Sample.git
cd WeatherCLI-Sample
npm install
npm run build
node dist/index.js --city "Paris"

Node.js >= 22 is required.

Usage

Default mode — current weather

weather-cli-sample
weather-cli-sample --city "Tokyo"
weather-cli-sample --lat 48.8566 --lon 2.3522

Auto-detects your location via IP geolocation when no location flag is given. Displays ASCII art, temperature, feels-like/UV, wind, sunrise/sunset, and moon phase inside a plain-ASCII box border.

Best weather within N driving hours

weather-cli-sample --max-hours 3
weather-cli-sample --max-hours 5 --units imperial

Scans all cities within N driving hours (haversine km / 80), scores each one, and prints the winner with distance and approximate drive time.

4-day forecast

weather-cli-sample --forecast
weather-cli-sample --forecast --city "London"

Prints four columns side-by-side: today plus the next three days, each with mini ASCII art, high/low temperature, and condition text.

Animated output (TTY only)

weather-cli-sample --animate

Loops a 2-frame ASCII animation (rain falling, sun pulsing, etc.) at 1 fps. Press Ctrl+C to exit. Skipped automatically on non-TTY output.

Machine-readable JSON

weather-cli-sample --json
weather-cli-sample --json --city "Sydney" | jq .tempC

Emits a typed JSON object to stdout. Schema documented at src/schemas/output.json.

All Flags

| Flag | Description | | ---- | ----------- | | --help, -h | Show usage and exit | | --city <name> | Fetch weather for a named city | | --lat <n> | Latitude in [-90, 90] (requires --lon) | | --lon <n> | Longitude in [-180, 180] (requires --lat) | | --max-hours <n> | Find best weather within N driving hours | | --forecast | Print 4-day side-by-side forecast | | --animate | Animated ASCII output (TTY only, Ctrl+C to stop) | | --json | Machine-readable JSON output (no ASCII art) | | --units metric\|imperial | Temperature units; default metric; persisted | | --no-color | Disable ANSI color (also respects NO_COLOR env var) | | --no-cache | Bypass the 24-hour weather cache and fetch fresh data | | --plain | Disable the ASCII box border |

Compatibility notes:

• --json takes precedence over --animate.
• --city and --lat/--lon cannot be combined.
• --units is saved to ~/.config/weather-cli-sample/config.json; a one-time hint is printed to stderr on first save so the persistence is never silent.

Sample Output

Sunny day in Barcelona

$ weather-cli-sample --city "Barcelona"

+--- Barcelona, ES (41.3851, 2.1734) ---+
|    \   |   /                          |
|     `.   .'                           |
|  --   (o)   --                        |
|     .'   `.                           |
|    /   |   \                          |
|        |                              |
|        |                              |
| Sunny  22C / 71.6F  [metric]          |
| Today: 25/18C  Sunny                  |
| Feels 21C / 69.8F  |  UV 5 (moderate) |
| Wind: -> 8 km/h                       |
| Sunrise 06:14  Sunset 20:47  Moon: waxing crescent |
+---------------------------------------+

Best-weather winner with --max-hours

$ weather-cli-sample --max-hours 3 --lat 41.39 --lon 2.16

+--- Girona, ES (41.9794, 2.8214) ---+
|    \   |   /                       |
|     `.   .'                        |
|  --   (o)   --                     |
|     .'   `.                        |
|    /   |   \                       |
|        |                           |
|        |                           |
| Sunny  24C / 75.2F  [metric]       |
| Today: 26/17C  Sunny               |
| Feels 23C / 73.4F  |  UV 7 (high)  |
| Wind: -> 6 km/h                    |
| Sunrise 06:12  Sunset 20:49  Moon: waxing crescent |
+------------------------------------+

Driving distance: 100 km (~1.2 h)

Rainy day in London

$ weather-cli-sample --city "London"

+--- London, GB (51.5074, -0.1278) ---+
|     _____                            |
|   .(     ).                          |
|  (_________)                         |
|  ' ' ' ' '                           |
| ' ' ' ' '                            |
|  ' ' ' ' '                           |
| ' ' ' ' '                            |
|                                      |
| Rain   11C / 51.8F  [metric]         |
| Today: 14/9C  Light rain             |
| Feels 9C / 48.2F  |  UV 1 (low)      |
| Wind: NE 19 km/h                     |
| Sunrise 05:02  Sunset 20:31  Moon: full |
+--------------------------------------+

4-day forecast view

$ weather-cli-sample --forecast --city "Paris"

 Today          Fri             Sat             Sun
 ============   ============   ============   ============
  \   |   /      _____          _____           \   |   /
   `.   .'      .(     ).      .(     ).          `.   .'
 --  (o)  --   (_________)    (_________)       --  (o)  --
   .'   `.     ' ' ' ' '      *  *  *  *          .'   `.

 Hi 21C  Lo 14C  Hi 17C  Lo 11C  Hi 12C  Lo 6C   Hi 19C  Lo 12C
 Sunny           Light rain      Snow            Sunny

JSON output

{
  "city": "Barcelona, ES",
  "tempC": 22,
  "tempF": 71.6,
  "condition": "Sunny",
  "conditionCode": 0,
  "humidity": 54,
  "apparentTempC": 21,
  "uvIndex": 5,
  "windSpeedKmh": 8,
  "windDirectionDeg": 90,
  "sunriseLocal": "06:14",
  "sunsetLocal": "20:47",
  "moonPhase": "waxing crescent",
  "today": { "highC": 25, "lowC": 18 },
  "score": 87.5
}

Weather Conditions

WeatherCLISample maps every WMO weather code into one of 7 visual buckets.

| Bucket | WMO Codes | Score | | ------ | --------- | ----- | | sun | 0, 1 | 100 | | partly-cloudy | 2 | 80 | | cloudy | 3 | 60 | | fog | 45, 48 | 35 | | rain | 51-57, 61-67, 80-82 | 25 | | snow | 71-77, 85-86 | 20 | | thunder | 95, 96, 99 | 0 |

Sample ASCII art for each bucket (as rendered in the terminal):

sun                   partly-cloudy        cloudy
    \   |   /              \  |  /            _____
     `.   .'                `.(o).'         .(     ).
  --   (o)   --           --  _____  --    (_________)
     .'   `.                 .(   ).          _____
    /   |   \               (________)      .(     ).
                                           (_________)

rain                  snow                 fog
  _____                 _____            _ _ _ _ _ _
.(     ).             .(     ).         _ _ _ _ _ _
(_________)           (_________)        _ _ _ _ _ _
' ' ' ' '             *  *  *  *       _ _ _ _ _ _
 ' ' ' ' '           *  *  *  *        _ _ _ _ _ _
' ' ' ' '             *  *  *  *      _ _ _ _ _ _

thunder
  _____
.(     ).
(_________)
    //
   //
  //\\
 //  \\

Comparison: WeatherCLISample vs wttr.in

| Feature | WeatherCLISample | wttr.in (curl) | | ------- | ------- | -------------- | | Install | npm i -g @bitmia/weather-cli-sample | none (curl) | | ASCII art | 7 buckets, plain ASCII only | Unicode art, emoji | | Legacy terminals | Yes (no Unicode required) | Partial (font-dependent) | | Forecast | --forecast (4 days, side-by-side) | yes (v2/v3 format) | | Animation | --animate (2-frame, TTY) | no | | JSON output | typed schema, optional fields | yes (j1/j2 formats) | | Radius best-weather | --max-hours N | no | | UV index | yes | no | | Feels-like temperature | yes | yes | | Wind speed + direction | yes | yes | | Sunrise / sunset | yes | yes | | Moon phase | yes (8 ASCII labels) | no | | Weather cache | 24h local cache | none | | ANSI color | yes, auto-off on pipe | yes | | NO_COLOR env | respected | no | | Weather scoring | 0-100 composite score | no | | Box-free output | --plain | no | | API key required | no | no | | Node.js required | yes (>=22) | no |

Scoring Formula

In --max-hours mode every candidate city is ranked by a 0-100 composite score. Higher is better.

score = 0.40 * tempComponent
      + 0.45 * conditionComponent
      + 0.15 * precipComponent

Temperature component (0-100). Piecewise linear. Plateau at 18-24 C = 100. Drops to 0 at -20 C and at 45 C.

Condition component (0-100). Flat lookup by bucket:

| Bucket | Score | | ------ | ----- | | sun | 100 | | partly-cloudy | 80 | | cloudy | 60 | | fog | 35 | | rain | 25 | | snow | 20 | | thunder | 0 |

Precipitation component (0-100). Exponential decay: 100 * exp(-mmPerHour / 2). 0 mm/h = 100; 2 mm/h ~= 37; 10 mm/h ~= 0.7.

Score is clamped to [0, 100] and rounded to two decimal places.

Haversine and Driving Time

Distances use the haversine formula on a sphere of radius 6371 km. This is great-circle (straight-line) distance — it ignores roads, terrain, and the actual route.

hours = haversineKm / 80

80 km/h is a fixed constant. Real drives are typically 20-50% longer. --max-hours N is a coarse radius filter, not a travel guarantee. Treat the printed ~X.X h as a lower bound.

Caveats

Scoring is heuristic. A 0-100 score is a tiebreaker, not a meteorologist's verdict. Temperature, condition, and precipitation are the only inputs.

Driving time is approximate. No routing, no traffic, no terrain. Use a maps app for real trip planning.

Publishing

The package is published as @bitmia/weather-cli-sample on npm.

npm login
npm test
npm run build
npm publish --access public

To verify after publish:

npx @bitmia/weather-cli-sample --help
npm install -g @bitmia/weather-cli-sample
weather-cli-sample --help

Weather data is sourced from Open-Meteo (primary) and wttr.in (fallback). Both are free and require no API key for reasonable usage.