feat(cli): add cli docs

docs/cli/_category_.json

@@ -0,0 +1,10 @@
+{
+  "position": 3,
+  "label": "Meteostat CLI",
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "title": "Meteostat CLI"
+  }
+}

docs/cli/configuration.md

@@ -0,0 +1,29 @@
+---
+title: Configuration | Meteostat CLI
+sidebar_label: Configuration
+sidebar_position: 4
+---
+
+# Configuration
+
+Manage the Meteostat CLI configuration. Settings are stored in a `cli.yml` file in the platform-specific app directory (e.g. `~/.config/meteostat/cli.yml` on Linux).
+
+## Usage
+
+```bash
+meteo config [KEY VALUE] [OPTIONS]
+```
+
+## Examples
+
+```bash
+meteo config --list                         # Show all current settings
+meteo config cache_enable false             # Disable caching
+meteo config interpolation_radius 25000     # Set interpolation radius to 25 km
+```
+
+## Options
+
+| Option   | Description                |
+| -------- | -------------------------- |
+| `--list` | Print all current settings |

docs/cli/overview.md

@@ -0,0 +1,55 @@
+---
+title: Meteostat CLI
+sidebar_label: Overview
+id: cli-overview
+slug: /cli
+sidebar_position: 1
+---
+
+import DocCardList from '@theme/DocCardList';
+
+# Meteostat CLI
+
+The Meteostat CLI gives you direct access to weather and climate data from the terminal. It is built on top of the [Meteostat Python library](/python) and lets you query historical observations, browse weather stations, and export data in a variety of formats — all without writing a single line of code.
+
+## 📚 Installation
+
+Install the CLI via [PyPI](https://pypi.org/project/meteostat-cli/):
+
+```bash
+pip install --user meteostat-cli
+```
+
+For plotting support (`png`/`svg` output), install the `plot` extra:
+
+```bash
+pip install --user meteostat-cli[plot]
+```
+
+## 🚀 Usage
+
+Want to know the hottest temperature of 2024 at Frankfurt Airport (station `10637`)? Run the following command:
+
+```bash
+meteo d 10637 -s 2024-01-01 -e 2024-12-31 -p tmax --agg max
+```
+
+This will yield the following output:
+
+```
+         tmax
+station
+10637    35.9
+```
+
+## ⚡ Shell Completion
+
+To enable shell completion (Bash, Zsh, Fish, PowerShell), run the following command:
+
+```bash
+meteo --install-completion
+```
+
+## 👀 Learn More
+
+<DocCardList />

docs/cli/stations/_category_.json

@@ -0,0 +1,10 @@
+{
+  "position": 2,
+  "label": "Weather Stations",
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "doc",
+    "id": "cli-stations-overview"
+  }
+}

docs/cli/stations/inventory.md

@@ -0,0 +1,37 @@
+---
+title: Inventory | Meteostat CLI
+sidebar_label: Inventory
+sidebar_position: 4
+---
+
+# Inventory
+
+Check what data is available for a weather station. You can filter by granularity and specific parameters to see exactly which records exist.
+
+## Usage
+
+```bash
+meteo inventory STATION_ID [OPTIONS]
+```
+
+Alias: `meteo i`
+
+## Examples
+
+```bash
+meteo inventory 10637
+meteo inventory 10637 --granularity daily
+meteo inventory 10637 --granularity daily --parameters tavg,tmin,tmax
+```
+
+## Options
+
+| Option          | Short | Description                                                     |
+| --------------- | ----- | --------------------------------------------------------------- |
+| `--granularity` | `-g`  | Filter by granularity: `hourly`/`h`, `daily`/`d`, `monthly`/`m` |
+| `--parameters`  | `-p`  | Comma-separated parameters (e.g. `tavg,tmin,tmax`)              |
+| `--providers`   | `-P`  | Comma-separated data providers                                  |
+| `--format`      | `-f`  | Output format: `csv`, `json`, `xlsx`, `parquet`                 |
+| `--output`      | `-o`  | Output file path (defaults to stdout)                           |
+| `--no-header`   |       | Omit CSV header row                                             |
+| `--all`         | `-A`  | Print full table without truncation                             |

docs/cli/stations/nearby.md

@@ -0,0 +1,37 @@
+---
+title: Nearby Stations | Meteostat CLI
+sidebar_label: Nearby Stations
+sidebar_position: 3
+---
+
+# Nearby Stations
+
+Find weather stations near a geographic location. Provide a latitude and longitude and the command returns the closest stations within the specified radius.
+
+## Usage
+
+```bash
+meteo nearby LAT LON [OPTIONS]
+```
+
+Alias: `meteo n`
+
+## Examples
+
+```bash
+meteo nearby 50.1109 8.6821                  # Nearest stations (default: 5 within 5 km)
+meteo nearby 50.1109 8.6821 --limit 10       # Return up to 10 stations
+meteo nearby 50.1109 8.6821 --radius 20000   # Search within 20 km
+meteo nearby 50.1109 8.6821 --format json    # JSON output
+```
+
+## Options
+
+| Option        | Short | Description                                     |
+| ------------- | ----- | ----------------------------------------------- |
+| `--limit`     | `-l`  | Maximum number of stations (default: 5)         |
+| `--radius`    | `-r`  | Search radius in meters (default: 5000)         |
+| `--format`    | `-f`  | Output format: `csv`, `json`, `xlsx`, `parquet` |
+| `--output`    | `-o`  | Output file path (defaults to stdout)           |
+| `--no-header` |       | Omit CSV header row                             |
+| `--all`       | `-A`  | Print full table without truncation             |

docs/cli/stations/overview.md

@@ -0,0 +1,49 @@
+---
+title: Weather Stations | Meteostat CLI
+sidebar_label: Overview
+id: cli-stations-overview
+slug: /cli/stations
+sidebar_position: 1
+---
+
+import DocCardList from '@theme/DocCardList';
+
+# Weather Stations
+
+The Meteostat CLI provides several commands to browse and look up weather stations. You can search by location, country, name, or various station identifiers, and inspect the availability of data for any station.
+
+## 🚀 Example
+
+Look up the metadata for Frankfurt Airport:
+
+```bash
+meteo station 10637
+```
+
+Find stations in Germany:
+
+```bash
+meteo station --country DE
+```
+
+Search for stations by name:
+
+```bash
+meteo station --name "Frankfurt"
+```
+
+Find the nearest stations to a location:
+
+```bash
+meteo nearby 50.1109 8.6821
+```
+
+Check what data is available for a station:
+
+```bash
+meteo inventory 10637
+```
+
+## 👀 Learn More
+
+<DocCardList />

docs/cli/stations/station.md

@@ -0,0 +1,46 @@
+---
+title: Station Lookup | Meteostat CLI
+sidebar_label: Station Lookup
+sidebar_position: 2
+---
+
+# Station Lookup
+
+Browse and search weather stations in the Meteostat network. You can look up a specific station by ID or filter stations by country, region, name, or various identifiers.
+
+## Usage
+
+```bash
+meteo station [ID] [OPTIONS]
+```
+
+Alias: `meteo s`
+
+## Examples
+
+```bash
+meteo station 10637                        # Metadata for a specific station
+meteo station --country DE                 # List stations by country
+meteo station --country DE --state HE      # Filter by country and state
+meteo station --name "Frankfurt"           # Search by name
+meteo station --wmo 10637                  # Look up by WMO ID
+meteo station --bbox 8.0,50.0,9.0,51.0     # Stations within a bounding box
+```
+
+## Options
+
+| Option        | Short | Description                                      |
+| ------------- | ----- | ------------------------------------------------ |
+| `--country`   | `-c`  | ISO 3166-1 alpha-2 country code                  |
+| `--state`     |       | State or region code                             |
+| `--name`      | `-n`  | Station name (partial match)                     |
+| `--wmo`       | `-w`  | WMO station ID                                   |
+| `--icao`      | `-i`  | ICAO station ID                                  |
+| `--iata`      |       | IATA station ID                                  |
+| `--national`  | `-N`  | National station ID                              |
+| `--bbox`      |       | Bounding box (`lon_min,lat_min,lon_max,lat_max`) |
+| `--sql`       |       | Arbitrary SQL query                              |
+| `--format`    | `-f`  | Output format: `csv`, `json`, `xlsx`, `parquet`  |
+| `--output`    | `-o`  | Output file path (defaults to stdout)            |
+| `--no-header` |       | Omit CSV header row                              |
+| `--all`       | `-A`  | Print full table without truncation              |

docs/cli/timeseries/_category_.json

@@ -0,0 +1,10 @@
+{
+  "position": 3,
+  "label": "Time Series",
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "doc",
+    "id": "cli-ts-overview"
+  }
+}

docs/cli/timeseries/daily.md

@@ -0,0 +1,34 @@
+---
+title: Daily Data | Meteostat CLI
+sidebar_label: Daily Data
+sidebar_position: 3
+---
+
+# Daily Data
+
+Fetch daily weather observations for one or more weather stations. Supports coordinate-based input for interpolated data.
+
+## Usage
+
+```bash
+meteo daily STATIONS... [OPTIONS]
+```
+
+Alias: `meteo d`
+
+## Examples
+
+```bash
+meteo daily 10637 --start 2024-01-01 --end 2024-12-31
+meteo d 10637 -s 2024-01-01 -e 2024-12-31              # Short form
+meteo daily 10637 10635 -s 2024-01-01 -e 2024-12-31   # Multiple stations
+meteo daily 50.1109,8.6821 -s 2024-01-01 -e 2024-12-31 # Coordinates (interpolation)
+meteo daily 10637 -s 2024-01-01 -e 2024-12-31 --parameters tavg,tmin,tmax,prcp
+meteo daily 10637 -s 2024-01-01 -e 2024-12-31 --agg max
+meteo daily 10637 -s 2024-01-01 -e 2024-12-31 --output data.json
+meteo daily 10637 -s 2024-01-01 -e 2024-12-31 --output chart.png
+```
+
+## Options
+
+See [common time series options](/cli/timeseries#common-options).

docs/cli/timeseries/hourly.md

@@ -0,0 +1,38 @@
+---
+title: Hourly Data | Meteostat CLI
+sidebar_label: Hourly Data
+sidebar_position: 2
+---
+
+# Hourly Data
+
+Fetch hourly weather observations for one or more weather stations. Supports coordinate-based input for interpolated data.
+
+## Usage
+
+```bash
+meteo hourly STATIONS... [OPTIONS]
+```
+
+Alias: `meteo h`
+
+## Examples
+
+```bash
+meteo hourly 10637 --start 2024-01-01 --end 2024-01-31
+meteo h 10637 -s 2024-01-01 -e 2024-01-31                     # Short form
+meteo hourly 10637 10635 -s 2024-01-01 -e 2024-01-31          # Multiple stations
+meteo hourly 50.1109,8.6821 -s 2024-01-01 -e 2024-01-07       # Coordinates (interpolation)
+meteo hourly 10637 -s 2024-01-01 -e 2024-01-31 --timezone Europe/Berlin
+meteo hourly 10637 -s 2024-01-01 -e 2024-01-31 --parameters tavg,prcp
+meteo hourly 10637 -s 2024-01-01 -e 2024-01-31 --output data.csv
+meteo hourly 10637 -s 2024-01-01 -e 2024-01-31 --output chart.png
+```
+
+## Options
+
+Hourly data supports all [common time series options](/cli/timeseries#common-options) plus:
+
+| Option       | Short | Description                                    |
+| ------------ | ----- | ---------------------------------------------- |
+| `--timezone` | `-t`  | Timezone for timestamps (e.g. `Europe/Berlin`) |

docs/cli/timeseries/monthly.md

@@ -0,0 +1,31 @@
+---
+title: Monthly Data | Meteostat CLI
+sidebar_label: Monthly Data
+sidebar_position: 4
+---
+
+# Monthly Data
+
+Fetch monthly weather summaries for one or more weather stations.
+
+## Usage
+
+```bash
+meteo monthly STATIONS... [OPTIONS]
+```
+
+Alias: `meteo m`
+
+## Examples
+
+```bash
+meteo monthly 10637 --start 2020 --end 2024
+meteo m 10637 -s 2020 -e 2024              # Short form
+meteo monthly 10637 10635 -s 2020 -e 2024  # Multiple stations
+meteo monthly 10637 -s 2020 -e 2024 --parameters tavg,prcp
+meteo monthly 10637 -s 2020 -e 2024 --output data.xlsx
+```
+
+## Options
+
+See [common time series options](/cli/timeseries#common-options).