path: root/man/prognosis.1

.TH PROGNOSIS 1 "2026-08-21" "prognosis" "User Commands"
.SH NAME
prognosis \- hour-by-hour terminal forecast with official Polish warnings
.SH SYNOPSIS
.B prognosis
.RI [ options ]
.RI [ place ]
.SH DESCRIPTION
.B prognosis
prints an hourly weather table, a temperature chart, and \(em for locations in
Poland \(em the meteorological warnings IMGW has issued for that powiat.
.PP
It needs no API key and has no third-party dependencies. Which columns appear,
in what order, and in which language is set by the configuration file; columns
the program does not ship with can be declared there too, so any field the
underlying APIs expose can be displayed. See
.B CUSTOM COLUMNS .
.PP
Output is pipe-safe: colour is switched off when standard output is not a
terminal, notes and diagnostics go to standard error, and
.B \-ascii
restricts output to ASCII for onward transmission by SMS.
.SH OPTIONS
.TP
.BI \-l " PLACE"
Place to query: a name, or
.IR lat , lon .
Overrides
.B location
in the configuration file for one run.
.TP
.BI \-n " N"
Show
.I N
hours ahead.
.TP
.BI \-d " N"
Show
.I N
days ahead, of 24 hours each. Mutually exclusive with
.BR \-n .
.TP
.BI \-pick " N"
Choose the
.IR N th
candidate for an ambiguous place name, and remember it. Re-resolves rather than
reading the cache, which is how a wrongly cached name is corrected.
.TP
.BI \-columns " LIST"
Comma-separated columns to display, overriding the configuration file.
.TP
.BI \-icons " SET"
Glyph set for the
.B icon
column:
.BR nerd ,
.BR emoji ,
or
.BR none .
.TP
.BI \-pollen " LIST"
Allergens to show for one run: a comma-separated list, or
.B all
or
.BR none .
.TP
.BI \-lang " LANG"
Display language:
.B en
or
.BR pl .
.TP
.B \-weather
Forecast only: omit sun times, the day summary, pollen and the chart.
.TP
.B \-no\-warnings
Omit IMGW warnings.
.TP
.B \-no\-graph
Table only, no chart.
.TP
.B \-no\-color
Plain output, no escape sequences.
.TP
.B \-ascii
Restrict output to ASCII. Intended for SMS, where a single non-ASCII character
forces the message from GSM\-7 (160 characters per segment) into UCS\-2 (70).
The degree sign becomes the unit letter and Polish diacritics are transliterated.
.TP
.B \-svg
Produce an SVG meteogram instead of the hourly table. See
.BR METEOGRAM .
.TP
.BI \-o " PATH" ", " \-out " PATH"
Write to
.I PATH
instead of standard output.
.PP
.RS
If
.I PATH
is an existing directory, or ends in a separator (in which case it is created),
a filename is generated from the place and the date, so repeated runs on
different days do not overwrite each other:
.IR krakow-pl-2026-08-27.svg .
Otherwise
.I PATH
is a filename, gaining
.B .svg
or
.B .txt
if it has none. A single
.B -
means standard output.
.PP
Colour is omitted when writing to a file, whatever the terminal would have
shown.
.RE
.TP
.B \-config
Print the path of the configuration file and exit.
.TP
.B \-version
Print the version and exit.
.SH CONFIGURATION
The configuration file is
.I $XDG_CONFIG_HOME/prognosis/config
(by default
.IR ~/.config/prognosis/config ).
It is written with commented defaults on first run. The format is one
.I KEY=VALUE
per line;
.B #
begins a comment; values are not quoted.
.PP
Command line flags override the file, and the file overrides the built-in
defaults.
.TP
.B location
Place to query. Required: prognosis has no other way to know where you are and
will not guess.
.TP
.B hours
Default span in hours.
.TP
.B units
.BR metric ", " imperial " or " si .
Passed to the provider, so rounding is theirs. Warning thresholds are always
compared in Celsius, whatever the display units.
.TP
.B columns
Columns to display, in order.
.TP
.B icons
.BR nerd ", " emoji " or " none .
.TP
.B graph ", " graph_height
Whether to draw the temperature chart, and over how many rows.
.TP
.B warnings
Whether to check IMGW for warnings.
.TP
.B pollen
Which allergens to report, or whether to report any:
.B none
omits the line entirely,
.B all
shows every species that has a reading, and a comma-separated list shows exactly
those species \(em even at zero, since a species you named is one you react to
and "none today" is the answer you wanted. With
.B all
nobody chose, so absent species are dropped rather than printing a line of
zeroes. Species:
.BR grass ", " birch ", " alder ", " mugwort ", " ragweed ", " olive .
.TP
.B color
.BR auto ", " always " or " never .
.TP
.B display_lang
.BR en " or " pl .
Covers everything prognosis writes itself. IMGW publishes its warning text in
Polish only, so that text remains Polish in either language.
.TP
.B ascii
Restrict output to ASCII, as
.BR \-ascii .
.SH COLUMNS
Built-in columns:
.BR hour ", " icon ", " temp ", " feels ", " conditions ", " mm ", " rain ", "
.BR wind ", " gusts ", " dir ", " humidity ", " dew ", " uv ", " cloud ", "
.BR pressure ", " visibility .
.PP
Only the fields the selected columns need are requested, so a narrow table
costs a smaller response. An unknown column name is an error at startup naming
the offender, never a silently blank column.
.PP
.B mm
and
.B rain
are hidden automatically when the window is dry and no hour reaches a 20%
chance of precipitation, and the day summary says
.I dry
instead.
.SH CUSTOM COLUMNS
Any field the two Open-Meteo APIs expose can be displayed, whether or not
prognosis knows about it. Declare a short name, then use it in
.BR columns .
.PP
.in +4n
.EX
columns=hour,temp,birch,soil,conditions

column.birch = air:birch_pollen
column.soil  = forecast:soil_temperature_0cm

label.soil     = soil
suffix.soil    = \(de
decimals.soil  = 0
label.birch    = birch
decimals.birch = 1
.EE
.in
.PP
.B column.\fINAME\fB = \fISOURCE\fB:\fIFIELD\fR
is the declaration.
.I SOURCE
is
.B forecast
(the weather API) or
.B air
(the air-quality API, which carries the allergens); they are separate services
with separate field sets, which is why the source must be given. An
.B air
column costs one extra request, made only when such a column is declared.
.PP
The remaining keys are optional:
.B label.\fINAME\fR
sets the header (default: the name),
.B width.\fINAME\fR
the column width (default: derived from the label),
.B decimals.\fINAME\fR
the digits after the point (default: 0), and
.B suffix.\fINAME\fR
a string appended to each value.
.PP
A custom name may not shadow a built-in column. A value the API does not supply
renders blank rather than as zero: for an allergen, "no data" and "none" are
different claims.
.SH METEOGRAM
.B \-svg
writes a standalone SVG: three panels sharing one time axis \(em temperature
with the apparent temperature dashed, precipitation as bars with the
probability as a dashed line against its own right-hand axis, and relative
humidity \(em over shaded night bands, with dates marked at midnight.
.PP
No plotting library or external program is involved: SVG is markup, so this
works on a machine with no graphics tooling at all.
.PP
.in +4n
.EX
prognosis \-l Krakow \-d 2 \-svg meteogram.svg
firefox meteogram.svg
rsvg\-convert \-o meteogram.png meteogram.svg
.EE
.in
.PP
The meteogram requests the fields it needs regardless of
.BR columns ,
so it is complete even when the table shows none of them.
.PP
Not every viewer reads from a pipe.
.BR feh (1)
does, given
.BR - ,
and so does
.BR chafa (1);
.BR nsxiv (1)
has no standard-input mode at all and prints its usage, which does not make the
cause obvious. Write the file first with
.B \-o
for those:
.PP
.in +4n
.EX
prognosis \-l Krakow \-svg | feh -
prognosis \-l Krakow \-svg | chafa
prognosis \-l Krakow \-svg \-o ~/tmp && nsxiv ~/tmp/krakow-pl-*.svg
.EE
.in
.PP
Most viewers handle the file itself, including
.BR nsxiv (1),
.BR feh (1),
.BR display (1)
and any browser, or
.BR chafa (1)
to draw it inside the terminal.
.BR convert (1)
may fall back to ImageMagick's own SVG renderer, which drops the curves;
.BR rsvg-convert (1)
does not.
.SH WARNINGS
IMGW publishes every warning in Poland, each tagged with the TERYT codes of the
powiats it covers. The coordinates are resolved to that code through GUGiK, so
warnings are filtered to your area rather than the whole country.
.PP
Four states are kept deliberately distinct, because silence must never be
mistaken for an all-clear:
.TP
warnings printed
In force for your powiat.
.TP
nothing printed
Checked; none in force.
.TP
.I warnings: could not check IMGW
The check itself failed.
.TP
.I warnings: IMGW covers Poland only
The location is outside Poland.
.SH FILES
.TP
.I ~/.config/prognosis/config
Configuration.
.TP
.I ~/.cache/prognosis/cache.json
Cached geocoding and TERYT lookups, one entry per line. Disposable: an entry
that will not parse is skipped and the rest kept; a file that will not parse at
all is moved aside to
.I cache.json.bad
rather than overwritten.
.SH EXIT STATUS
.TP
.B 0
Success.
.TP
.B 1
The forecast could not be fetched.
.TP
.B 2
Usage error: bad flags, an invalid configuration, no location set, or an
ambiguous place name.
.SH EXAMPLES
.TP
.B prognosis
The next twelve hours where you live.
.TP
.B prognosis \-l krakow \-d 3
Three days for another place.
.TP
.B prognosis \-weather \-ascii \-no\-warnings \-n 6
A short, ASCII-only forecast suitable for sending by SMS.
.SH SEE ALSO
.BR wego (1)
.PP
Data from Open-Meteo (https://open-meteo.com/), GUGiK
(https://services.gugik.gov.pl/) and IMGW (https://danepubliczne.imgw.pl/).
.SH AUTHOR
Lukasz Kasprzak.