1 files changed, 91 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5a5a8e7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,91 @@
+# `wx` - a command line interface for aviation weather
+
+`wx` fetches weather data from the NOAA Aviation Weather Center's Text Data
+Server (TDS).
+
+## Installation from source
+
+1. Clone the repository
+2. Run `sudo make install`
+
+## Usage
+
+Currently, we support fetching METARs in a variety of methods. When fetching
+METARs, a time constraint must be supplied. A time constraint can either be in
+the form "past x" or "between x and y".
+
+    $ wx metar --past 3h
+    $ wx metar --since 2020-01-01T00:00:00 --until 2020-01-02T00:00:00
+
+The `--past` argument defaults to `1h`, so if none of `--past`, `--since`, or
+`--until` are specified, METARs from the past hour will be fetched.
+
+Note that the TDS only stores METARs from the past three days, so the `wx`
+command cannot effectively be used to pull historical data.
+
+### For a set of stations
+
+You can fetch METARs from a set of stations by their full or partial ICAO IDs:
+
+    $ wx metar kbos
+    $ wx metar kbos ksea
+    $ wx metar kb
+
+### For stations in a region
+
+You can fetch METARs from all stations within a rectangular or radial region.
+Rectangular regions are specified by a `minLat,minLon,maxLat,maxLon` tuple:
+
+    $ wx metar --rect 39,-70,40,-71
+
+Radial regions are specified as a radius in statute miles around a center point
+as a `dist,lat,lon` tuple:
+
+    $ wx metar --radial 5.5,40,-70
+
+### For stations along a flight path
+
+You can fetch weather for all stations with a distance of a specified flight
+path. A flight path is specified by a series of `--waypoint` arguments, where
+each waypoint can be an ICAO identifier or a `lon,lat` tuple. Waypoints must be
+specified in order from origin to destination.
+
+    $ wx metar --path-dist 10 --waypoint ksea --waypoint kbos
+
+### Controlling density
+
+When running a query which will return METARs from many stations, it may be
+helpful to reduce the density of the results. This can be done with the
+`--min-dist` argument which specifies a minimum distance (in degrees of latitude
+or longitude) between stations to display. Providing a higher value for
+`--min-dist` will result in fewer stations being returned.
+
+    $ wx metar \
+      --path-dist 10 --waypoint ksea --waypoint kbos \
+      --min-dist 5 \
+
+### Filtering recency
+
+There are two mechanisms for filtering results by recency. First, you can
+request the single most recent METAR from all the stations being fetched:
+
+    $ wx metar --past 6h kbos ksea --most-recent
+
+Even though we've specified two stations, KBOS and KSEA, we'll only get a single
+METAR back from whichever of the two stations most recently made an observation.
+
+The second filtering mechanism is `--most-recent-by-station`. This argument can
+take several values:
+
+* `constraint` (default): request the most recent for each METAR station in the
+  fastest fashion.
+* `postfilter`: filter results after applying all other constraints.
+* `false`: don't filter results to only the most recent for each station.
+
+## Contributing
+
+Email patches to <mailto:~benburwell/patchall@lists.sr.ht>.
+
+## License
+
+MIT