What you are seeing

Look up at sky, then to your screen, now back up to the sky, now down again. Chances are when looking up you did not see the Moon, but there was a Moon on your screen.

Presented for your consideration is a rendering of the Moon in glorious 7-bit ASCII. Drag the slider with the Moon icon, and you will notice the Moon changes over time.

As the Moon orbits around the Earth in a monthly cycle, the visible portion of the Moon change as part of the Moon hides in its own shadow. This is called the Lunar phase. The illuminated percentage and side are accurately calculated and displayed.

The orbit itself is not circular and the Lunar distance to the Earth is not constant. Variation in distance causes the apparent size of the Moon to change. This is also accurately calculated and displayed.

Additionally, the Moon wobbles slightly up and down and side to side in its orbit. This is called Lunar libration. The libration angle is also accurately calculated and is visible in the ASCII art.

Lastly, depending on observer’s position on the Earth and time of day, changes Moon’s apparent angular orientation. This is not modeled at all, because I don’t know where you are.

Breathe (In the Terminal)

Now that we got that astronomy out of the way, let’s get the ASCII in to your terminal. You have 2 choices. First, you can fetch the ASCII from the webserver at the present url. A curl command is helpfully provided in the virtual terminal above to fetch the ASCII for a given date, but it will fetch today’s date if no date is provided.

curl -s "https://aleyan.com/projects/ascii-side-of-the-moon?date=2025-09-01"

Alternatively, you can get the ascii-side-of-the-moon package from npmjs.com and run it locally. For your convenience, npx will install and run the package for you. The command also takes an optional date argument.

npx ascii-side-of-the-moon 2025-09-01

Implementations details

The ascii-side-of-the-moon npm package is MIT licensed and available on GitHub. The Lunar calculations were made via the excellent astronomy-engine package by CosineKitty. Images of the Moon were rendered in Blender from gerhald3d’s Moon 2K 3D model for a variety of distances and libration. Chafa was used to create the ASCII representation of the resulting .pngs.

Money

This website is statically hosted on Cloudflare Pages free tier. The serverless function to serve https for curl is also on the Cloudflare free tier. To make it work, the javascript bundle had to be under 3 MB in size and respond under 10 milliseconds CPU time. The ascii-side-of-the-moon package was designed with those constraints in mind.