Add orientation CLI and config documentation

2026-06-11 14:10:27 +00:00
parent a97de4c720
commit b4bdd2e4f1
5 changed files with 257 additions and 25 deletions
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -0,0 +1,68 @@
+# weatherapi CLI
+
+## Shortest Useful Command
+
+```sh
+go run ./cmd/weatherapi -config config.yml
+```
+
+This starts the HTTP API with the supplied YAML configuration. The configured
+Postgres database must be reachable, and `templates.base_dir` must point to the
+text response templates when text output is used.
+
+## Command Overview
+
+`weatherapi` is the service executable in `cmd/weatherapi`. It loads
+configuration, opens configured database handles, selects the first configured
+database as the primary weather data store, registers HTTP endpoints, and starts
+the feedapi HTTP runtime.
+
+Build and run a local binary:
+
+```sh
+go build -o ./weatherapi ./cmd/weatherapi
+./weatherapi -config config.yml
+```
+
+Run with the default config path:
+
+```sh
+./weatherapi
+```
+
+## Flag Reference
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `-config` | `WEATHERAPI_CONFIG` when set, otherwise `config.yml` | Path to the YAML config file. |
+
+`weatherapi` does not currently expose other CLI flags.
+
+## Environment Variables
+
+| Variable | Description |
+| --- | --- |
+| `WEATHERAPI_CONFIG` | Default config path used when `-config` is not provided and the value is not blank. |
+
+Command-line flags take precedence over environment defaults.
+
+## Config Path Precedence
+
+1. `-config /path/to/config.yml`
+2. non-blank `WEATHERAPI_CONFIG`
+3. `config.yml` in the current working directory
+
+## Startup and Shutdown
+
+Startup fails if configuration cannot be loaded, no database is configured, a
+configured database cannot be opened, the primary database cannot be selected,
+or the HTTP app cannot be constructed.
+
+The process listens for `SIGINT` and `SIGTERM`. When a signal is received, the
+runtime context is canceled and feedapi performs graceful HTTP shutdown. Database
+close errors during shutdown are logged.
+
+## Related Docs
+
+- [`docs/config.md`](config.md): YAML configuration reference
+- [`docs/api.md`](api.md): public HTTP API reference