WHAT

ascii-side-of-the-moon is a small library that prints an ascii representation of the moon on a given date.

For a given date it returns a 29 row by 60 column string.

CLI Usage

You can use this package directly from the command line:

# Show moon for current date
npx ascii-side-of-the-moon

# Show moon for a specific date
npx ascii-side-of-the-moon 2025-09-19

# Include a specific UTC time (quote when using spaces)
npx ascii-side-of-the-moon "2025-09-19 21:30"

# Provide an observer location (latitude/longitude in degrees, optional elevation in meters)
# (Latitude and longitude are optional, but both must be supplied together;
#  elevation is ignored unless lat/lon are provided.)
npx ascii-side-of-the-moon 2025-09-19T21:30 --lat 37.7749 --lon -122.4194 --elevation 25

# Choose a reference frame for the moon orientation
npx ascii-side-of-the-moon 2025-09-19 --frame=celestial_up      # Celestial north up (default without lat/lon)
npx ascii-side-of-the-moon 2025-09-19 --frame=celestial_down    # Celestial south up (inverted)
npx ascii-side-of-the-moon 2025-09-19 --frame=observer --lat 40.7 --lon -74  # Observer view (zenith up)

The CLI will display the ASCII moon art along with information about the moon's phase, illumination percentage, distance, and angular diameter. When an observer location is supplied, the renderer also knows the altitude/azimuth and can draw the horizon line to show whether the moon is above or below your local horizon.

Frame Options

• celestial_up - Standard geocentric orientation with celestial north up (default when no lat/lon provided)
• celestial_down - Inverted orientation with celestial south up
• observer - Observer-relative orientation with zenith up, uses parallactic angle (default when lat/lon provided)

Example

import { getMoonState, renderMoon, getMoonPhase } from 'ascii-side-of-the-moon';

// Get moon state for January 1st, 2025
const date = new Date(2025, 0, 1); // Note: month is 0-based in JavaScript
const moonState = getMoonState(date);

// Get the moon phase name
const phaseName = getMoonPhase(moonState);
console.log(`Moon Phase: ${phaseName}`); // e.g., "Waxing Crescent"

// Render the moon's ASCII representation
const moonAscii = renderMoon(moonState);

// Print to console
console.log(moonAscii);

API Reference

getMoonState(date: Date, observer?: ObserverLocation): MoonState

Returns detailed moon information including phase, size, and libration data. If you pass an observer (latitude/longitude in degrees, optional elevation in meters), the returned MoonState also contains topocentric position (altitude, azimuth, parallactic angle); this enables horizon-aware rendering and correct rotation for your sky.

renderMoon(moonState: MoonState, options?: RenderOptions): string

Renders the moon as ASCII art. Returns a 29×60 character string.

RenderOptions includes:

• showHorizon (default true for observer frame): set to false to suppress the horizon overlay
• frame: Reference frame for the moon orientation:
  • "celestial_up" - Celestial north up (default when no position data)
  • "celestial_down" - Celestial south up (180° rotation)
  • "observer" - Observer's zenith up, uses parallactic angle (default when position data available)

getMoonPhase(moonState: MoonState): string

Returns the English name of the moon phase (e.g., "New Moon", "Waxing Crescent", "First Quarter", "Waxing Gibbous", "Full Moon", "Waning Gibbous", "Last Quarter", "Waning Crescent").

Local Demo

Inside of repository for ascii-side-of-the-moon.

Render a single date:

# Show moon for current date
pnpm run render:demo

# Show moon for a specific date
pnpm run render:demo 2025-01-01

# Include a specific UTC time
pnpm run render:demo 2025-01-01 21:30

# Include observer location (enables parallactic rotation and horizon display)
pnpm run render:demo 2025-01-01 21:30 --lat 40.7128 --lon -74.0060

# With elevation (meters)
pnpm run render:demo 2025-01-01 21:30 --lat 37.7749 --lon -122.4194 --elevation 25

# Just observer location (uses current date/time)
pnpm run render:demo --lat 40.7128 --lon -74.0060

# Choose a reference frame
pnpm run render:demo 2025-01-01 --frame=celestial_up      # Celestial north up
pnpm run render:demo 2025-01-01 --frame=celestial_down    # Celestial south up (inverted)
pnpm run render:demo 2025-01-01 --frame=observer --lat 40.7 --lon -74  # Observer view

Render an animation:

pnpm run render:demo_animate 2025-01-01 2025-12-30

# Include observer coordinates (latitude/longitude degrees, optional elevation meters)
pnpm run render:demo_animate 2025-07-25 2025-08-23 --lat 37.7749 --lon -122.4194 --elevation 25

Both demo scripts now include the moon phase name in their output.

Char aspect ratio.

This package assumes a character ratio of 10/22.

Preview image

The preview svg was generated with these commands:

asciinema rec -c "pnpm run render:demo_animate 2025-07-25 2025-08-23" moon.cast
cat moon.cast | npx svg-term-cli --out=moon.svg