isobar-cli 1.2.0

A visually pleasing terminal weather tool focusing on Real Feel and Windchill.

Isobar CLI

A terminal weather tool designed to provide a fast, clean sense of what the weather feels like outside; right now and for the week ahead. Built with Python and Rich.

Philosophy

Isobar CLI answers a simple question: "What does it feel like outside right now, and do I need a jacket?"

Most weather apps overwhelm with data. Isobar strips away everything except what matters when deciding how to prepare for the day.

Design Principles

• Essential over comprehensive — Show Real Feel, not 47 data points.
• Terminal-native — Built for quick checks within a developer workflow.
• Zero friction — No API keys or configuration files required.
• Information density — Clean, borderless UI for maximum readability.
• Intentional features — Each feature must answer: "Does this help someone understand what it feels like outside?"

✨ Features

• Auto-Location — isobar detects the city automatically 🌍
• Weather Condition Icons — WMO-standard emoji + plain-English description (☀️ Clear sky, 🌨️ Moderate snow, ⛈️ Thunderstorm)
• Real Feel — Apparent temperature metrics (what it actually feels like).
• Air Quality Index — US AQI with health classifications 😷
• 7-Day Forecast — Full week outlook with color-coded highs/lows and daily rain %
• Hourly Outlook — Next 12 hours of temperature and rain chance (--hourly)
• Multiple Cities — Compare weather across several cities side-by-side.
• Smart Suggestions — Fuzzy city name matching if there is a typo.
• Shell Completion — Tab-complete city names based on search history.
• Dynamic Timezone — Sunrise/sunset shown in the city's local time, not yours.
• Precipitation Forecast — Next 6h rain/snow chance and totals.
• Smart Caching — 15-minute cache per city (~/.cache/isobar/)
• Color-Coded Temps — Intuitive color mapping for temperature ranges.
• Metric Support — --metric or -m for Celsius, km/h, and mm.
• No API Keys — Free Open-Meteo and ip-api.com.
• Zero Config — Works instantly after installation.
• Phase 7: Intuition & Analysis — Higher-level context and automated insights:
  • Preparation Guidance — Clothing and gear suggestions based on conditions 🧥☂️🧴
  • Temporal Context — Comparison with previous day conditions 📈
  • UV Index Monitoring — Sun protection guidance with intensity levels ☀️
  • Wind Gust Alerts — Highlighting of significant gust events 💨⚠️
  • Home City Persistence — Set a default city with isobar home "Your City" 🏠 (Note: Due to a Typer limitation, this currently shows weather for "Home, Kansas" instead of setting home city. Manual config editing required.)

🚀 Installation

The recommended way to install Isobar is via pipx:

pipx install isobar-cli

Installation is also supported via Homebrew:

brew install KnowOneActual/tap/isobar

Note: Installing via Homebrew builds several high-performance dependencies (like numpy and h3) from source. This ensures a robust, isolated install but may take 5-10 minutes to complete.

Alternatively, install directly from PyPI:

pip install isobar-cli

Or install from source:

git clone https://github.com/KnowOneActual/isobar-cli.git
cd isobar-cli
pip install .

📱 Usage

# Auto-detect location
isobar

# Specify a city
isobar Chicago
isobar London Tokyo Paris     # Multiple cities
isobar "New York"             # Use quotes for multi-word cities

# Hourly outlook (next 12h)
isobar --hourly Chicago
isobar -H Chicago

# 7-day forecast
isobar --forecast Chicago
isobar -f Chicago

# Note: Flags must come before city names
# ✅ isobar -H Chicago
# ❌ isobar Chicago -H  (treats "-H" as a city name)
isobar "San Francisco" --forecast
isobar -f Sydney

# Metric units (Celsius, km/h, mm)
isobar --metric
isobar -m
isobar Tokyo -m

# Home city management
isobar home "New York"    # Set home city
isobar home               # Show current home city
isobar home --clear       # Clear home city
isobar                    # Uses home city if set (otherwise auto-detects)

⚙️ Configuration

Isobar supports configuration via environment variables for advanced use cases:

API Endpoint Configuration

Customize API endpoints for different weather providers or testing:

# Use custom weather APIs
export ISOBAR_GEOCODING_URL="https://custom-geocoding-api.example.com/v1/search"
export ISOBAR_WEATHER_URL="https://custom-weather-api.example.com/v1/forecast"
export ISOBAR_AQI_URL="https://custom-aqi-api.example.com/v1/air-quality"

# Run with custom endpoints
isobar "New York"

Timezone Support

For enhanced timezone accuracy (optional):

# Install optional timezone support
pip install isobar-cli[timezone]

# Sunrise/sunset will now display in local timezone
isobar London

Debug Mode

Enable debug logging to stderr:

# View API errors and debugging information
isobar "Test City" 2> debug.log

⌨️ Shell Completion

Isobar supports tab-completion for city names. To enable it for a shell:

Zsh:

isobar --install-completion zsh

Bash:

isobar --install-completion bash

(Note: A terminal restart may be required after installation).

🖥️ Example Output

               Chicago, Illinois Weather
 ☀️  Conditions:                        Mainly clear
 🌡️  Temperature:                             75.2°F
 🤔  Real Feel:                               78.5°F
 💨  Wind Speed:                             12.4 mph
 💧  Humidity:                                   65%
 ☔  Precip Chance:  30% (6h) | Light rain likely
 🌅  Sunrise:                                6:29 AM
 🌇  Sunset:                                 5:37 PM
 ☀️  UV Index:                              6.5 (High)
 💨  Wind Alert:                     ⚠️ Gusts up to 25 mph
 😷  Air Quality:                        45 (Good)

↑ 5.2°F warmer than yesterday

Preparation Guidance:
  • 🧥 Light jacket
  • 🧴 Sunscreen recommended
  • 🕶️ Sunglasses recommended

           7-Day Forecast — Chicago, Illinois
  Day            Conditions        High     Low   Rain%  UV
  Today      ☁️  Overcast         78.7°F  63.9°F    30%   7.2
  Tue Apr 1  ⛅  Partly cloudy    82.4°F  65.4°F    20%   8.1
  Wed Apr 2  🌦️  Light drizzle    76.8°F  60.9°F    45%   5.8
  Thu Apr 3  ☀️  Clear sky        80.3°F  63.5°F    10%   8.5
  Fri Apr 4  ☀️  Clear sky        83.6°F  67.1°F     5%   9.0
  Sat Apr 5  ⛅  Partly cloudy    79.8°F  64.9°F    15%   7.8
  Sun Apr 6  🌤️  Mainly clear     81.2°F  66.3°F    10%   8.3

🛠 Tech Stack

Tool	Purpose
Typer	CLI framework
Rich	Terminal UI
Open-Meteo	Weather and forecast data
ipwho.is	Auto-location detection
timezonefinder	Dynamic timezone resolution
pytest	Unit testing framework
requests-mock	API testing
Ruff	Linting and formatting
pip-audit	Dependency security scanning
Phase 7 Features	Intuition & Analysis
config.py	Persistent home city configuration
Enhanced logic.py	Preparation guidance, UV monitoring, gust alerts
Updated ui.py	Contextual display of insights
v1.2.0 Features	Security & Configuration
Configurable API Endpoints	Environment variable support for custom APIs
Enhanced Error Handling	Specific exception catching with timeouts
Timezone Support	Optional pytz dependency for local time display

🔒 Security

Security is a fundamental priority for Isobar CLI. Multiple layers of automated scanning ensure the tool remains safe and secure for all users.

Security Measures

• Vulnerability Scanning: Trivy scans the filesystem and dependencies for known vulnerabilities.
• Static Analysis (SAST): Bandit and Semgrep analyze the code for insecure patterns.
• Dependency Auditing: pip-audit and GitHub Dependabot ensure third-party packages stay updated.
• Script Linting: ShellCheck enforces best practices for Bash scripts.
• Secret Scanning: Automated checks prevent the accidental commitment of sensitive credentials.

All security scans are integrated into the CI/CD pipeline and run on every push, pull request, and weekly schedule. Results are available via the GitHub Security tab.

📈 Project Status

✅ Phase 1 Complete — Caching and Auto-Location
✅ Phase 2 Complete — Precipitation, Sunrise/Sunset, and Condition Icons
✅ Phase 3 Complete — 7-Day Forecast, Dynamic Timezone, and UI Refinements
✅ Phase 4 Complete — Quality & Trust (Security, CI/CD)
✅ Phase 5 Complete — Testing & Reliability
✅ Phase 6 Complete — Distribution (PyPI, Homebrew)
✅ Phase 7 Complete — Intuition & Analysis (v1.1.0)
✅ v1.2.0 Complete — Security & Configuration Enhancements
Refer to ROADMAP.md and CHANGELOG.md for details.

🤝 Contributing

Detailed instructions are available in CONTRIBUTING.md. New features must answer: "Does this help someone understand what it feels like outside?"

📄 License

MIT. See LICENSE.