# Weather CLI
A simple, fast, and feature-rich command-line weather tool with multiple data sources and output formats.
## Features
- 🌍 **Multiple location input types**: City names, ZIP codes, coordinates (decimal & DMS), auto-detection
- 📊 **Multiple output formats**: Simple, visual, raw JSON
- 📐 **Unit systems**: Metric and Imperial units
- 🏃♂️ **Fast and lightweight**: Minimal dependencies, quick responses
- 💾 **Smart caching**: 5-minute cache to reduce API calls
- 🌐 **Multiple data sources**: Open-Meteo (implemented), wttr.in and NWS (planned)
- ⚙️ **Configurable**: Config file and command-line options
## Installation
```bash
# Clone the repository
git clone https://github.com/mikebc23/weather-cli.git
cd weather-cli
# Install in development mode
pip install -e .
# Or install from source
pip install .
```
## Quick Start
```bash
# Current location (auto-detect via IP)
weather
# City names
weather "New York"
weather "San José, Costa Rica"
weather "Tokyo"
# Coordinates
weather "40.7128,-74.0060" # NYC
weather "9.9281,-84.0907" # San José, CR
weather --lat=51.5074 --lon=-0.1278 # London
# Different output formats
weather "Tokyo" --format=visual
weather "London" --format=simple --units=imperial
weather "NYC" --format=raw # JSON output
```
## Output Formats
### Simple (default)
```text
San José, CR: 22°C, Partly Cloudy
Feels like: 25°C | Humidity: 65% | Wind: 8 km/h
```
### Visual
```text
San José, CR
\ / 22°C
.-. Partly Cloudy
― ( ) ― ↗ 8 km/h
`-' 65% humidity
/ \
```
### Raw JSON
```json
{
"location": {
"name": "San José, Costa Rica",
"latitude": 9.9281,
"longitude": -84.0907,
"country": "Costa Rica"
},
"current": {
"temperature_2m": 22.5,
"relative_humidity_2m": 65,
"apparent_temperature": 25.1,
"wind_speed_10m": 8.2,
"condition": "Partly cloudy",
"pressure_msl": 1013.2,
"cloud_cover": 25,
"uv_index": 3.2
},
"units": {
"temperature": "°C",
"wind_speed": "km/h",
"pressure": "hPa"
},
"source": "open-meteo",
"timestamp": "2025-07-14T15:30:00Z",
"cache_hit": false
}
```
## Command Line Options
```text
weather [location] [options]
Positional Arguments:
location Location (city, ZIP code, coordinates, or auto-detect)
Location Options:
--lat LAT Latitude (use with --lon)
--lon LON Longitude (use with --lat)
Format Options:
--format FORMAT Output format: simple, visual, raw (default: simple)
--units UNITS Unit system: metric, imperial (default: metric)
Data Source Options:
--source SOURCE Weather source: open-meteo, wttr, nws (default: open-meteo)
--timeout TIMEOUT HTTP timeout in seconds (default: 10)
Cache Options:
--no-cache Disable cache usage
--clear-cache Clear cache and exit
Other Options:
--config CONFIG Path to configuration file
--debug Enable debug output
--version Show version
--help Show help message
```
## Configuration
The tool uses a configuration file at `~/.weather.conf` (JSON format):
```json
{
"units": "metric",
"format": "simple",
"source": "open-meteo",
"cache_duration": 300,
"timeout": 10
}
```
## Supported Location Formats
| Format | Example | Description |
|--------|---------|-------------|
| Auto-detect | `weather` | Uses IP geolocation |
| City name | `"New York"` | City, country, or address |
| ZIP code | `"10001"` | US ZIP codes (5 or 9 digits) |
| Decimal coordinates | `"40.7128,-74.0060"` | Latitude,longitude |
| Explicit coordinates | `--lat=40.7128 --lon=-74.0060` | Separate lat/lon flags |
| DMS coordinates | `"40°42'46.0\"N 74°00'21.6\"W"` | Degrees, minutes, seconds |
## Project Structure
```text
weather-cli/
├── weather/ # Main package
│ ├── main.py # CLI entry point
│ ├── config.py # Configuration management
│ ├── cache.py # Caching system
│ ├── location.py # Location services (geocoding)
│ ├── sources/ # Weather data sources
│ │ ├── base.py # Abstract base class
│ │ ├── open_meteo.py # Open-Meteo API
│ │ ├── wttr.py # wttr.in service
│ │ └── nws.py # National Weather Service
│ ├── formatters/ # Output formatters
│ │ ├── base.py # Abstract formatter
│ │ ├── simple.py # Simple text output
│ │ ├── visual.py # Visual ASCII art format
│ │ └── raw.py # Raw JSON output
│ └── utils/ # Utility functions
│ ├── http.py # HTTP client wrapper
│ ├── units.py # Unit conversions
│ └── exceptions.py # Custom exceptions
├── tests/ # Test suite
│ ├── conftest.py # pytest fixtures
│ └── test_location.py # Location tests
├── setup.py # Package setup
├── requirements.txt # Dependencies
└── README.md # This file
```
## Data Sources
### Open-Meteo (Primary)
- **Status**: Implemented and working
- **Coverage**: Global
- **Features**: Current weather, forecasts, no API key required
- **Rate limit**: Generous free tier
- **URL**: https://open-meteo.com/
### wttr.in (Planned)
- **Status**: Placeholder implemented
- **Coverage**: Global
- **Features**: Simple curl-based service, ASCII art built-in
- **Rate limit**: Fair use
### National Weather Service (Planned)
- **Status**: Placeholder implemented
- **Coverage**: United States only
- **Features**: Official US government weather data
- **Rate limit**: None (government API)
## Dependencies
- `requests>=2.25.0` - HTTP requests
- `urllib3>=1.26.0` - HTTP client utilities
Development dependencies:
- `pytest` - Testing framework
## Testing
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=weather
# Run specific test file
pytest tests/test_location.py -v
```
## Examples
```bash
# Different locations
weather # Auto-detect
weather "Paris, France" # City name
weather "90210" # ZIP code
weather "35.6762,139.6503" # Tokyo coordinates
# Different formats and units
weather "London" --format=visual --units=imperial
weather "Moscow" --format=simple --units=metric
weather "Sydney" --format=raw # JSON output
# Using explicit coordinates
weather --lat=55.7558 --lon=37.6173 # Moscow
weather --lat=-33.8688 --lon=151.2093 # Sydney
# Configuration and caching
weather "NYC" --no-cache # Skip cache
weather --clear-cache # Clear cache
weather "NYC" --timeout=5 # Custom timeout
```
## Error Handling
The tool provides clear error messages for common issues:
- **Location not found**: "Location error: Place not found: Invalid City"
- **Invalid coordinates**: "Location error: Invalid latitude: 91.0. Must be between -90 and 90"
- **Network issues**: "Weather data error: Failed to get weather from Open-Meteo: Connection timeout"
- **Invalid format**: "Error: Unknown format: badformat"
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for your changes
5. Run tests (`pytest`)
6. Commit your changes (`git commit -am 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [Open-Meteo](https://open-meteo.com/) for providing excellent free weather API
- [OpenStreetMap Nominatim](https://nominatim.org/) for geocoding services
- Weather icons inspired by wttr.in ASCII art
Raw data
{
"_id": null,
"home_page": "https://github.com/mikebc23/weather-cli",
"name": "cr-mb-weather-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Michael Barquero",
"author_email": "Michael Barquero <mike@mb.cr>",
"download_url": "https://files.pythonhosted.org/packages/cf/de/d728009aa453111cc8345c4d24d0ff9f4d01cfdde5f4dcb302227e0bf551/cr_mb_weather_cli-1.0.0.tar.gz",
"platform": null,
"description": "# Weather CLI\n\nA simple, fast, and feature-rich command-line weather tool with multiple data sources and output formats.\n\n## Features\n\n- \ud83c\udf0d **Multiple location input types**: City names, ZIP codes, coordinates (decimal & DMS), auto-detection\n- \ud83d\udcca **Multiple output formats**: Simple, visual, raw JSON\n- \ud83d\udcd0 **Unit systems**: Metric and Imperial units\n- \ud83c\udfc3\u200d\u2642\ufe0f **Fast and lightweight**: Minimal dependencies, quick responses\n- \ud83d\udcbe **Smart caching**: 5-minute cache to reduce API calls\n- \ud83c\udf10 **Multiple data sources**: Open-Meteo (implemented), wttr.in and NWS (planned)\n- \u2699\ufe0f **Configurable**: Config file and command-line options\n\n## Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/mikebc23/weather-cli.git\ncd weather-cli\n\n# Install in development mode\npip install -e .\n\n# Or install from source\npip install .\n```\n\n## Quick Start\n\n```bash\n# Current location (auto-detect via IP)\nweather\n\n# City names\nweather \"New York\"\nweather \"San Jos\u00e9, Costa Rica\"\nweather \"Tokyo\"\n\n# Coordinates\nweather \"40.7128,-74.0060\" # NYC\nweather \"9.9281,-84.0907\" # San Jos\u00e9, CR\nweather --lat=51.5074 --lon=-0.1278 # London\n\n# Different output formats\nweather \"Tokyo\" --format=visual\nweather \"London\" --format=simple --units=imperial\nweather \"NYC\" --format=raw # JSON output\n```\n\n## Output Formats\n\n### Simple (default)\n\n```text\nSan Jos\u00e9, CR: 22\u00b0C, Partly Cloudy\nFeels like: 25\u00b0C | Humidity: 65% | Wind: 8 km/h\n```\n\n### Visual\n\n```text\nSan Jos\u00e9, CR\n \\ / 22\u00b0C\n .-. Partly Cloudy\n \u2015 ( ) \u2015 \u2197 8 km/h\n `-' 65% humidity\n / \\\n```\n\n### Raw JSON\n\n```json\n{\n \"location\": {\n \"name\": \"San Jos\u00e9, Costa Rica\",\n \"latitude\": 9.9281,\n \"longitude\": -84.0907,\n \"country\": \"Costa Rica\"\n },\n \"current\": {\n \"temperature_2m\": 22.5,\n \"relative_humidity_2m\": 65,\n \"apparent_temperature\": 25.1,\n \"wind_speed_10m\": 8.2,\n \"condition\": \"Partly cloudy\",\n \"pressure_msl\": 1013.2,\n \"cloud_cover\": 25,\n \"uv_index\": 3.2\n },\n \"units\": {\n \"temperature\": \"\u00b0C\",\n \"wind_speed\": \"km/h\",\n \"pressure\": \"hPa\"\n },\n \"source\": \"open-meteo\",\n \"timestamp\": \"2025-07-14T15:30:00Z\",\n \"cache_hit\": false\n}\n```\n\n## Command Line Options\n\n```text\nweather [location] [options]\n\nPositional Arguments:\n location Location (city, ZIP code, coordinates, or auto-detect)\n\nLocation Options:\n --lat LAT Latitude (use with --lon)\n --lon LON Longitude (use with --lat)\n\nFormat Options:\n --format FORMAT Output format: simple, visual, raw (default: simple)\n --units UNITS Unit system: metric, imperial (default: metric)\n\nData Source Options:\n --source SOURCE Weather source: open-meteo, wttr, nws (default: open-meteo)\n --timeout TIMEOUT HTTP timeout in seconds (default: 10)\n\nCache Options:\n --no-cache Disable cache usage\n --clear-cache Clear cache and exit\n\nOther Options:\n --config CONFIG Path to configuration file\n --debug Enable debug output\n --version Show version\n --help Show help message\n```\n\n## Configuration\n\nThe tool uses a configuration file at `~/.weather.conf` (JSON format):\n\n```json\n{\n \"units\": \"metric\",\n \"format\": \"simple\",\n \"source\": \"open-meteo\",\n \"cache_duration\": 300,\n \"timeout\": 10\n}\n```\n\n## Supported Location Formats\n\n| Format | Example | Description |\n|--------|---------|-------------|\n| Auto-detect | `weather` | Uses IP geolocation |\n| City name | `\"New York\"` | City, country, or address |\n| ZIP code | `\"10001\"` | US ZIP codes (5 or 9 digits) |\n| Decimal coordinates | `\"40.7128,-74.0060\"` | Latitude,longitude |\n| Explicit coordinates | `--lat=40.7128 --lon=-74.0060` | Separate lat/lon flags |\n| DMS coordinates | `\"40\u00b042'46.0\\\"N 74\u00b000'21.6\\\"W\"` | Degrees, minutes, seconds |\n\n## Project Structure\n\n```text\nweather-cli/\n\u251c\u2500\u2500 weather/ # Main package\n\u2502 \u251c\u2500\u2500 main.py # CLI entry point\n\u2502 \u251c\u2500\u2500 config.py # Configuration management\n\u2502 \u251c\u2500\u2500 cache.py # Caching system\n\u2502 \u251c\u2500\u2500 location.py # Location services (geocoding)\n\u2502 \u251c\u2500\u2500 sources/ # Weather data sources\n\u2502 \u2502 \u251c\u2500\u2500 base.py # Abstract base class\n\u2502 \u2502 \u251c\u2500\u2500 open_meteo.py # Open-Meteo API\n\u2502 \u2502 \u251c\u2500\u2500 wttr.py # wttr.in service\n\u2502 \u2502 \u2514\u2500\u2500 nws.py # National Weather Service\n\u2502 \u251c\u2500\u2500 formatters/ # Output formatters\n\u2502 \u2502 \u251c\u2500\u2500 base.py # Abstract formatter\n\u2502 \u2502 \u251c\u2500\u2500 simple.py # Simple text output\n\u2502 \u2502 \u251c\u2500\u2500 visual.py # Visual ASCII art format\n\u2502 \u2502 \u2514\u2500\u2500 raw.py # Raw JSON output\n\u2502 \u2514\u2500\u2500 utils/ # Utility functions\n\u2502 \u251c\u2500\u2500 http.py # HTTP client wrapper\n\u2502 \u251c\u2500\u2500 units.py # Unit conversions\n\u2502 \u2514\u2500\u2500 exceptions.py # Custom exceptions\n\u251c\u2500\u2500 tests/ # Test suite\n\u2502 \u251c\u2500\u2500 conftest.py # pytest fixtures\n\u2502 \u2514\u2500\u2500 test_location.py # Location tests\n\u251c\u2500\u2500 setup.py # Package setup\n\u251c\u2500\u2500 requirements.txt # Dependencies\n\u2514\u2500\u2500 README.md # This file\n```\n\n## Data Sources\n\n### Open-Meteo (Primary)\n\n- **Status**: Implemented and working\n- **Coverage**: Global\n- **Features**: Current weather, forecasts, no API key required\n- **Rate limit**: Generous free tier\n- **URL**: https://open-meteo.com/\n\n### wttr.in (Planned)\n\n- **Status**: Placeholder implemented\n- **Coverage**: Global\n- **Features**: Simple curl-based service, ASCII art built-in\n- **Rate limit**: Fair use\n\n### National Weather Service (Planned)\n\n- **Status**: Placeholder implemented\n- **Coverage**: United States only\n- **Features**: Official US government weather data\n- **Rate limit**: None (government API)\n\n## Dependencies\n\n- `requests>=2.25.0` - HTTP requests\n- `urllib3>=1.26.0` - HTTP client utilities\n\nDevelopment dependencies:\n\n- `pytest` - Testing framework\n\n## Testing\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=weather\n\n# Run specific test file\npytest tests/test_location.py -v\n```\n\n## Examples\n\n```bash\n# Different locations\nweather # Auto-detect\nweather \"Paris, France\" # City name\nweather \"90210\" # ZIP code\nweather \"35.6762,139.6503\" # Tokyo coordinates\n\n# Different formats and units\nweather \"London\" --format=visual --units=imperial\nweather \"Moscow\" --format=simple --units=metric\nweather \"Sydney\" --format=raw # JSON output\n\n# Using explicit coordinates\nweather --lat=55.7558 --lon=37.6173 # Moscow\nweather --lat=-33.8688 --lon=151.2093 # Sydney\n\n# Configuration and caching\nweather \"NYC\" --no-cache # Skip cache\nweather --clear-cache # Clear cache\nweather \"NYC\" --timeout=5 # Custom timeout\n```\n\n## Error Handling\n\nThe tool provides clear error messages for common issues:\n\n- **Location not found**: \"Location error: Place not found: Invalid City\"\n- **Invalid coordinates**: \"Location error: Invalid latitude: 91.0. Must be between -90 and 90\"\n- **Network issues**: \"Weather data error: Failed to get weather from Open-Meteo: Connection timeout\"\n- **Invalid format**: \"Error: Unknown format: badformat\"\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for your changes\n5. Run tests (`pytest`)\n6. Commit your changes (`git commit -am 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [Open-Meteo](https://open-meteo.com/) for providing excellent free weather API\n- [OpenStreetMap Nominatim](https://nominatim.org/) for geocoding services\n- Weather icons inspired by wttr.in ASCII art\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A fast, feature-rich command-line weather tool",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/mikebc23/weather-cli/issues",
"Homepage": "https://github.com/mikebc23/weather-cli",
"Source": "https://github.com/mikebc23/weather-cli"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "731ff8761e783ec4876617ac17029d98dce78c53975bbc9391190b78ac04d071",
"md5": "b7fc9adb9256fb13141e720d10db2c98",
"sha256": "26c1b72216bf14d9c8648c31273c304917955846781180cd5d8c6455a7ddc6ef"
},
"downloads": -1,
"filename": "cr_mb_weather_cli-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b7fc9adb9256fb13141e720d10db2c98",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 31497,
"upload_time": "2025-07-19T03:27:25",
"upload_time_iso_8601": "2025-07-19T03:27:25.024892Z",
"url": "https://files.pythonhosted.org/packages/73/1f/f8761e783ec4876617ac17029d98dce78c53975bbc9391190b78ac04d071/cr_mb_weather_cli-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cfded728009aa453111cc8345c4d24d0ff9f4d01cfdde5f4dcb302227e0bf551",
"md5": "29fff645ce902747a051283fab13a8d4",
"sha256": "d35cacd01bc8220078946f5803863940d612188fccecff35fd73074022c249fc"
},
"downloads": -1,
"filename": "cr_mb_weather_cli-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "29fff645ce902747a051283fab13a8d4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26489,
"upload_time": "2025-07-19T03:27:27",
"upload_time_iso_8601": "2025-07-19T03:27:27.257956Z",
"url": "https://files.pythonhosted.org/packages/cf/de/d728009aa453111cc8345c4d24d0ff9f4d01cfdde5f4dcb302227e0bf551/cr_mb_weather_cli-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 03:27:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mikebc23",
"github_project": "weather-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
">=",
"1.26.0"
]
]
}
],
"lcname": "cr-mb-weather-cli"
}
JSON
