weathercli

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 12, 2026 License: MIT Imports: 7 Imported by: 0

README

☀️ weathercli — Simple Weather CLI for LLMs & Humans

CI Go Report Card

Fast weather CLI built for LLM integration and human readability. Get current weather or forecasts for any location worldwide.

Highlights

  • Current weather conditions with temp, humidity, wind
  • Daily forecast (up to 16 days)
  • Hourly forecast (up to 16 days)
  • Location search by name (geocoding)
  • JSON output for LLM parsing
  • Color human output (respects NO_COLOR)
  • Free API (Open-Meteo) — no key required
  • Works worldwide

Install / Run

# From source
cd weathercli
go build -o weathercli cmd/weathercli/main.go

# Or with go install
go install github.com/pjtf93/weathercli/cmd/weathercli@latest

CLI

weathercli [--json] [--no-color] [--verbose] <command>

Commands:
  current   Get current weather for a location
  forecast  Get weather forecast for a location
  search    Search for location coordinates
Current Weather
# By location name
weathercli current "New York"
weathercli current "London, UK"
weathercli current "Tokyo, Japan"

# JSON output for LLMs
weathercli current "Paris" --json
Forecast
# Daily forecast (default: 7 days)
weathercli forecast "Berlin" --days 7

# Hourly forecast
weathercli forecast "Madrid" --hourly --hours 24

# JSON output
weathercli forecast "Sydney" --days 5 --json
Search Locations
# Find coordinates for a location
weathercli search "San Francisco"
weathercli search "Barcelona" --json

Library Usage

package main

import (
    "context"
    "fmt"
    "github.com/pjtf93/weathercli"
)

func main() {
    client := weathercli.NewClient()
    
    // Get current weather
    weather, err := client.Current(context.Background(), "London")
    if err != nil {
        panic(err)
    }
    fmt.Printf("Temperature: %.1f°C\n", weather.Temperature)
    
    // Get forecast
    forecast, err := client.Forecast(context.Background(), "Paris", 7)
    if err != nil {
        panic(err)
    }
    for _, day := range forecast.Daily {
        fmt.Printf("%s: %.1f°C\n", day.Date, day.TempMax)
    }
}

API

Uses Open-Meteo - a free weather API:

  • No API key required
  • No rate limits for non-commercial use
  • Global coverage
  • High accuracy data from multiple sources

Testing

go test ./...
go test -v ./...

LLM Integration

Perfect for AI agents and scripts:

# Get structured JSON output
weathercli current "San Francisco" --json | jq .temperature
weathercli forecast "Berlin" --days 5 --json | jq '.daily[0].condition'

# Example LLM tool/function call
{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "parameters": {
    "location": "Paris, France"
  },
  "command": "weathercli current 'Paris, France' --json"
}
JSON Output Structure
Current Weather
{
  "location": {
    "name": "London",
    "latitude": 51.5074,
    "longitude": -0.1278,
    "country": "United Kingdom",
    "timezone": "Europe/London"
  },
  "time": "2024-01-12T14:30:00Z",
  "temperature": 10.3,
  "apparent": 8.1,
  "humidity": 86,
  "wind_speed": 12.2,
  "wind_direction": 202,
  "condition": "Overcast",
  "weather_code": 3
}
Forecast
{
  "location": { ... },
  "daily": [
    {
      "date": "2024-01-12",
      "temp_max": 12.1,
      "temp_min": 4.3,
      "condition": "Slight rain",
      "precip_prob": 75,
      "sunrise": "2024-01-12T08:04:00Z",
      "sunset": "2024-01-12T16:45:00Z"
    }
  ]
}

Notes

  • All temperatures in Celsius
  • Wind speed in km/h
  • Precipitation in mm / snowfall in cm
  • Times in location's local timezone
  • Geocoding uses Open-Meteo's built-in service
  • No API key required, free for non-commercial use
  • Weather codes follow WMO standard (0-99)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Quick Development Setup
# Clone and test
git clone https://github.com/pjtf93/weathercli.git
cd weathercli
go test ./...

# Build
make build
# or
go build -o weathercli ./cmd/weathercli

License

MIT License - see LICENSE for details.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var WeatherCode = map[int]string{
	0:  "Clear sky",
	1:  "Mainly clear",
	2:  "Partly cloudy",
	3:  "Overcast",
	45: "Foggy",
	48: "Depositing rime fog",
	51: "Light drizzle",
	53: "Moderate drizzle",
	55: "Dense drizzle",
	56: "Light freezing drizzle",
	57: "Dense freezing drizzle",
	61: "Slight rain",
	63: "Moderate rain",
	65: "Heavy rain",
	66: "Light freezing rain",
	67: "Heavy freezing rain",
	71: "Slight snow",
	73: "Moderate snow",
	75: "Heavy snow",
	77: "Snow grains",
	80: "Slight rain showers",
	81: "Moderate rain showers",
	82: "Violent rain showers",
	85: "Slight snow showers",
	86: "Heavy snow showers",
	95: "Thunderstorm",
	96: "Thunderstorm with slight hail",
	99: "Thunderstorm with heavy hail",
}

WeatherCode maps WMO weather codes to human-readable conditions.

Functions

func GetCondition 

func GetCondition(code int) string

GetCondition returns human-readable condition from weather code.

func WindDirection 

func WindDirection(degrees int) string

WindDirection returns compass direction from degrees.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client handles weather API requests.

func NewClient 

func NewClient(opts ...Options) *Client

NewClient creates a new weather client.

func (*Client) Current 

func (c *Client) Current(ctx context.Context, location string) (*CurrentWeather, error)

Current fetches current weather for a location.

func (*Client) CurrentByCoords 

func (c *Client) CurrentByCoords(ctx context.Context, lat, lon float64, loc *Location) (*CurrentWeather, error)

CurrentByCoords fetches current weather by coordinates.

func (*Client) Forecast 

func (c *Client) Forecast(ctx context.Context, location string, days int, hourly bool) (*Forecast, error)

Forecast fetches weather forecast for a location.

func (*Client) ForecastByCoords 

func (c *Client) ForecastByCoords(ctx context.Context, lat, lon float64, days int, hourly bool, loc *Location) (*Forecast, error)

ForecastByCoords fetches forecast by coordinates.

func (*Client) SearchLocation 

func (c *Client) SearchLocation(ctx context.Context, query string) ([]Location, error)

SearchLocation finds locations by name.

type CurrentWeather 

type CurrentWeather struct {
	Location      Location  `json:"location"`
	Time          time.Time `json:"time"`
	Temperature   float64   `json:"temperature"`   // °C
	Apparent      float64   `json:"apparent"`      // Feels like °C
	Humidity      int       `json:"humidity"`      // %
	Precipitation float64   `json:"precipitation"` // mm
	Rain          float64   `json:"rain"`          // mm
	Snowfall      float64   `json:"snowfall"`      // cm
	WindSpeed     float64   `json:"wind_speed"`    // km/h
	WindDirection int       `json:"wind_direction"`
	Pressure      float64   `json:"pressure"` // hPa
	CloudCover    int       `json:"cloud_cover"`
	Visibility    float64   `json:"visibility"` // meters
	UVIndex       float64   `json:"uv_index"`
	WeatherCode   int       `json:"weather_code"`
	Condition     string    `json:"condition"` // Human-readable
}

CurrentWeather represents current weather conditions.

type DailyForecast 

type DailyForecast struct {
	Date          time.Time `json:"date"`
	TempMax       float64   `json:"temp_max"`
	TempMin       float64   `json:"temp_min"`
	ApparentMax   float64   `json:"apparent_max"`
	ApparentMin   float64   `json:"apparent_min"`
	Precipitation float64   `json:"precipitation"`
	Rain          float64   `json:"rain"`
	Snowfall      float64   `json:"snowfall"`
	WindSpeedMax  float64   `json:"wind_speed_max"`
	WindDirection int       `json:"wind_direction"`
	UVIndexMax    float64   `json:"uv_index_max"`
	PrecipProb    int       `json:"precip_prob"` // %
	Sunrise       time.Time `json:"sunrise"`
	Sunset        time.Time `json:"sunset"`
	WeatherCode   int       `json:"weather_code"`
	Condition     string    `json:"condition"`
}

DailyForecast represents a single day's forecast.

type Forecast 

type Forecast struct {
	Location Location         `json:"location"`
	Daily    []DailyForecast  `json:"daily,omitempty"`
	Hourly   []HourlyForecast `json:"hourly,omitempty"`
}

Forecast represents weather forecast data.

type HourlyForecast 

type HourlyForecast struct {
	Time          time.Time `json:"time"`
	Temperature   float64   `json:"temperature"`
	Apparent      float64   `json:"apparent"`
	Humidity      int       `json:"humidity"`
	Precipitation float64   `json:"precipitation"`
	Rain          float64   `json:"rain"`
	Snowfall      float64   `json:"snowfall"`
	WindSpeed     float64   `json:"wind_speed"`
	WindDirection int       `json:"wind_direction"`
	Pressure      float64   `json:"pressure"`
	CloudCover    int       `json:"cloud_cover"`
	Visibility    float64   `json:"visibility"`
	UVIndex       float64   `json:"uv_index"`
	PrecipProb    int       `json:"precip_prob"`
	WeatherCode   int       `json:"weather_code"`
	Condition     string    `json:"condition"`
}

HourlyForecast represents a single hour's forecast.

type Location 

type Location struct {
	Name      string  `json:"name"`
	Latitude  float64 `json:"latitude"`
	Longitude float64 `json:"longitude"`
	Country   string  `json:"country,omitempty"`
	Admin1    string  `json:"admin1,omitempty"` // State/Province
	Timezone  string  `json:"timezone,omitempty"`
}

Location represents a geographic location with coordinates.

type Options 

type Options struct {
	BaseURL    string
	GeoBaseURL string
	Timeout    time.Duration
}

Options for creating a new client.

Source Files

View all Source files

Directories

Path Synopsis
cmd
weathercli command
Package main implements the weathercli CLI entrypoint.
 Package main implements the weathercli CLI entrypoint.
internal
cli

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.