astroterm: a terminal star map in C with configurable sky views and ASCII rendering

What astroterm renders and who the C-based terminal planetarium is for

astroterm is a C program that turns a terminal into a star map. It calculates and renders the real-time positions of stars, planets, constellations and lunar phases as ASCII characters, using only what the terminal provides: no graphical display server, no network connection and no external database service. All astronomical data ships with the binary.

The project is aimed at engineers and astronomy enthusiasts who want a sky view that works in constrained environments: a remote SSH session, a headless server, or a slow terminal where a graphical planetarium is not an option. It also makes a screensaver on any UNIX-like system that supports the terminal.

Any date and time can be specified, not only the present moment, which lets users examine past conjunctions, future eclipses or historical sky configurations for a given location. Version v1.2.0 was released on 2026-04-01, following v1.1.0 on 2026-03-29, and the last push was on 2026-09-11. Licensing is MIT.

Installing via pacman, dnf, Homebrew, Guix or a prebuilt binary

astroterm is in several package repositories. On Arch Linux, it is available from the extra repository:

pacman -S astroterm

On Fedora 40 and later:

sudo dnf install astroterm

On macOS with Homebrew:

brew install astroterm

Guix users can install it after a `guix pull`:

guix package --install astroterm

For platforms without a package manager entry, prebuilt binaries are at the Releases page. On Linux and macOS, download the binary for your platform using wget with the appropriate os and arch tokens, make it executable, then run it:

chmod +x ./astroterm
./astroterm

On Windows, PowerShell's `Invoke-WebRequest` fetches `astroterm-win-x86_64.exe` from the Releases page; the .exe runs directly after download. Linux arm64 is not yet available in the prebuilt binaries, and Windows prebuilts cover only x86_64. For any architecture without a prebuilt, CONTRIBUTING.md documents the source build process.

Latitude, longitude, UTC datetime and magnitude threshold: the four view parameters

astroterm's sky view is shaped primarily by four flags. The observer latitude (-a, --latitude) accepts values from -90 to 90 degrees, defaulting to 0.0. Longitude (-o, --longitude) runs from -180 to 180 degrees, also defaulting to 0.0. Both defaults place the observer at the equatorial zero meridian, which is over open ocean west of Africa: any meaningful sky view requires supplying real coordinates.

The datetime flag (-d, --datetime) takes a UTC timestamp in the format yyyy-mm-ddThh:mm:ss. No default value is listed in the --help output for this flag, unlike latitude and longitude. Setting a past date reproduces a historical sky; setting a future date previews an upcoming one.

The star magnitude threshold (-t, --threshold) defaults to 5.0 and controls which stars are rendered: only stars brighter than the given value appear. Astronomical magnitude runs inversely, so a threshold of 1.0 shows only the very brightest objects while 5.0 approaches the edge of comfortable naked-eye visibility. A separate label threshold (-l, --label-thresh) defaults to 0.25 and controls which stars receive name labels independently of whether they are rendered.

Animation speed is set by -s (--speed), defaulting to 1.0, which scales how quickly the sky moves in real time. Frame rate is -f (--fps), defaulting to 24.

Why constellations vanish when the magnitude threshold is too high

Constellation stick figures (-C, --constellations) have a strict visibility rule: a constellation is drawn only if every star in its stick figure falls above the threshold. This is documented in the --help output: "Note: a constellation is only drawn if all stars in the figure are over the threshold." A single dim star in a constellation's figure is enough to suppress the entire pattern.

This interacts with the default threshold of 5.0 in a way that may be surprising. Most prominent constellations include at least one member star dimmer than 5.0, so -C alone may produce fewer constellations than expected. Lowering the threshold with -t draws more stars, which allows more complete stick figures to appear.

The azimuthal grid (-g, --grid) adds orientation lines to the view for identifying directions and elevation angles. Metadata display (-m, --metadata) adds informational fields alongside the rendering, though the --help output does not list which metadata fields appear.

The --aspect-ratio (-r) flag also appears in the --help output, but its description is cut off in the README before it completes. The README does not document what aspect-ratio adjustment does or what values it accepts.

Color, Unicode, Braille and what each mode requires from the terminal

Three flags change how astroterm draws its output. Color (-c, --color) enables ANSI terminal colors; without it, the rendering is monochrome. Unicode mode (-u, --unicode) replaces ASCII characters with Unicode equivalents, which produces finer-grained rendering where the terminal supports them. Braille mode (-b, --braille) uses Braille characters for constellation lines and requires Unicode to be enabled first, a dependency noted in the --help output.

A Nix example combining both unicode and color flags appears in the installation section with this syntax:

nix-shell -I nixpkgs=channel:nixpkgs-unstable -p astroterm --command "astroterm -u -c"

This shows how to pass argument flags inside the Nix shell wrapper. On any other platform, the same flags combine directly on the command line.

Terminals without Unicode support fall back to ASCII silently when -u is not passed. Whether a given terminal emulator renders Braille characters clearly depends on the font in use; no specific emulators or fonts are listed as tested. Running astroterm on a terminal with poor Unicode coverage may produce garbled constellation lines rather than a clean rendering failure.

The quit-on-any flag (-q, --quit-on-any) changes exit behavior: without it, only q or ESC exits the program. With the flag, any keypress terminates the view, which suits running astroterm as a screensaver where an accidental key should end it.

Linux arm64 not yet supported; Windows and macOS have prebuilt binaries for specific architectures

Among the platform-specific constraints, Linux arm64 is explicitly unresolved: arm64 support depends on Ubuntu arm64 runners becoming available on GitHub Actions, as stated in the prebuilt installation section. macOS arm64 (Apple Silicon, the aarch64 architecture) is supported in the prebuilt binaries. On Windows, only x86_64 is available in the prebuilt .exe; no Windows arm64 binary is mentioned.

For comparison, a desktop planetarium like Stellarium offers richer visualisation with mouse interaction, a catalog of millions of objects, real-time tracking and click-to-identify functionality. astroterm's advantage over Stellarium or similar tools is that it requires no GUI framework, runs over SSH without X forwarding, and installs as a single binary. It renders the naked-eye sky well; deep-sky objects and fine catalog work are outside what ASCII characters in a terminal can represent.

This also applies to time-based use: astroterm plays back the sky as an animation but does not offer an interactive scrubber to move through time. Adjusting the datetime requires restarting with a new -d value.

Meson build system, MIT licence and the repository structure

astroterm uses Meson as its build system, with meson.build in the repository root; no CMake or autotools files are present. Source files are under src/, headers under include/, test cases under test/ and bundled astronomical data under data/. CI runs through GitHub Actions, with test coverage reported by Codecov. CONTRIBUTING.md covers the full build, test and contribution process for anyone who needs to build from source or submit changes.

Licensing is MIT, with the LICENSE file in the repository root. MIT terms permit redistribution and modification with attribution.

Release versioning follows a standard semantic format: v1.2.0 on 2026-04-01, v1.1.0 on 2026-03-29, v1.0.10 on 2026-01-16. All published releases carry standard tags with no edge or pre-release qualifier. Both the Citations and Data Sources sections in the README list the astronomical references and datasets behind the rendering, though neither section is included in the README text in the repository.

Editorial conclusion

astroterm fits engineers who want a real-time sky view inside a terminal, running over SSH or as a screensaver. It is not a substitute for a full-featured planetarium when you need mouse interaction, a deep catalog or click-to-identify objects. Before running it, set -a and -o to your actual latitude and longitude: the defaults are both 0.0, placing the observer over open ocean at the equatorial zero meridian. Verify your terminal supports Unicode before using -u or -b, and check the Releases page for a prebuilt that matches your platform before attempting a source build from CONTRIBUTING.md.

Frequently asked questions

Official sources

1. da-luce/astroterm on GitHub
2. Issues
3. License: MIT
4. README
5. Releases