Command-line interface

The main entry point is:

ephemeris-tools <command> [options]

where <command> is one of ephemeris, tracker, or viewer.

Global options

These options are available on every subcommand:

-v / --verbose

Enable verbose logging (INFO level). Without this flag only warnings and errors are printed. Default: off.

ephemeris-tools ephemeris -v --planet saturn --start "2025-01-01" ...

Ephemeris command

Generate a time-series ephemeris table (planet/moon geometry at each time step).

ephemeris-tools ephemeris [options]

Example:

ephemeris-tools ephemeris --planet saturn --start "2025-01-01 00:00" \
    --stop "2025-01-02 00:00" --interval 1 --time-unit hour \
    --columns ymdhms radec phase --moons mimas enceladus \
    -o ephem.txt

Planet and time range

--planet

Planet number (4-9) or case-insensitive name. Values: 4 / mars, 5 / jupiter, 6 / saturn, 7 / uranus, 8 / neptune, 9 / pluto. Default: 6 (Saturn).

--planet saturn
--planet 5

--start

Start time as a date/time string. Default: "" (empty; required for a meaningful run).

--start "2025-01-01 00:00"

--stop

Stop time as a date/time string. Default: "" (empty; required for a meaningful run).

--stop "2025-01-03 00:00"

--interval

Time step size (in units given by --time-unit). Default: 1.0.

--interval 12

--time-unit

Unit for --interval. Values: sec, min, hour, day. Default: hour.

--time-unit day

--ephem

Ephemeris version number. 0 selects the latest available version. Available versions are listed in SPICE_planets.txt under SPICE_PATH. Default: 0.

--ephem 0

Observer position

--observer

Convenience shortcut that sets the observer in one argument. Accepts a single name (e.g. earth, Cassini), the keyword latlon followed by latitude, longitude, and optional altitude (e.g. 19.82 -155.47 4205), or a numeric latitude/longitude/altitude triple. When given, --observer takes precedence over --viewpoint, --observatory, --latitude, --longitude, and --altitude. Default: not set.

--observer earth
--observer Cassini
--observer 19.82 -155.47 4205

--viewpoint

Observer type. Use observatory to observe from a named observatory or spacecraft (specified by --observatory), or latlon to observe from a geographic position on Earth (specified by --latitude / --longitude / --altitude). Default: observatory.

--viewpoint observatory
--viewpoint latlon

--observatory

Observatory or spacecraft name (used when --viewpoint is observatory). Default: "Earth's center". Accepted spacecraft names (case-insensitive): Voyager 1 (VG1), Voyager 2 (VG2), Galileo (GLL), Cassini (CAS), New Horizons (NH), Juno (JNO), Europa Clipper (EC), JUICE (JCE), JWST, HST. See Argument reference for the full table.

--observatory "Earth's center"
--observatory Cassini

--latitude

Observer latitude in degrees (used when --viewpoint is latlon). Default: not set.

--viewpoint latlon --latitude 19.82

--longitude

Observer longitude in degrees (used when --viewpoint is latlon). Default: not set.

--viewpoint latlon --longitude -155.47

--lon-dir

Whether --longitude is measured east or west of the prime meridian. Values: east, west. Default: east.

--longitude 155.47 --lon-dir west

--altitude

Observer altitude in metres above sea level (used when --viewpoint is latlon). Default: not set (treated as 0).

--viewpoint latlon --latitude 19.82 --longitude -155.47 --altitude 4205

--sc-trajectory

Spacecraft trajectory file variant (used with spacecraft observers). Default: 0.

--observatory Cassini --sc-trajectory 1

Columns and moons

--columns

Columns to include in the ephemeris table. Accepts integer IDs, string names, or a mix. See Argument reference for the full list. Default: 1 2 3 15 8 (MJD, YMDHM, YMDHMS, RA/Dec, phase angle).

--columns 1 2 3 15 8
--columns ymdhms radec phase

--mooncols

Columns to include for each moon in the ephemeris table. Accepts integer IDs, string names, or a mix. See Argument reference for the full list. Default: 5 6 8 9 (RA offset, Dec offset, distance, phase angle).

--mooncols 5 6 8 9
--mooncols radec offset phase

--moons

Moons to include. Accepts 1-based indices, NAIF IDs (>=100), or case-insensitive names. See Argument reference for per-planet moon lists. Default: none.

--moons 1 2 3
--moons mimas enceladus titan
--moons 1 titan 603

Output

-o / --output

Write the ephemeris table to a file. If not given, output is written to stdout. Default: stdout.

-o saturn_ephem.txt

--cgi

Read all parameters from environment variables (CGI mode) instead of the command line. Used for web-server integration. Default: off.

--cgi

Tracker command

Generate a moon tracker PostScript plot showing moon positions over time, with an optional text table.

ephemeris-tools tracker [options]

Example:

ephemeris-tools tracker --planet saturn --start "2025-01-01 00:00" \
    --stop "2025-01-02 00:00" --interval 1 --time-unit hour \
    --moons mimas enceladus tethys dione rhea titan \
    --rings main ge --title "Saturn moons" \
    -o tracker.ps --output-txt tracker.txt

Planet and time range

--planet: Same as ephemeris. Default: 6 (Saturn).
--start: Same as ephemeris. Default: "" (required).
--stop: Same as ephemeris. Default: "" (required).
--interval: Same as ephemeris. Default: 1.0.
--time-unit: Same as ephemeris. Default: hour.
--ephem: Same as ephemeris. Default: 0.

Observer position

The observer arguments --observer, --viewpoint, --observatory, --latitude, --longitude, --lon-dir, --altitude, and --sc-trajectory are the same as ephemeris with identical defaults.

Moons and rings

--moons

Moons to plot. Same format as ephemeris. Default: when not specified, all moons in the planet configuration are plotted (the set and count depend on the planet).

--moons mimas enceladus titan

--rings

Ring option codes or case-insensitive names. Integers and names can be mixed. The available options depend on the planet; see Argument reference for the full list. Default: none.

--rings main ge
--rings 61 62

Plot options

--xrange

Half-range of the x-axis in units given by --xunit. Default: auto-calculated from the outermost moon’s orbit.

--xrange 200

--xunit

Units for the x-axis. Values: arcsec, radii. Default: arcsec.

--xunit radii

--title

Plot title string. Default: "" (no title).

--title "Saturn moons Jan 2025"

Output

-o / --output

Write the PostScript plot to a file. Default: none (no PS output).

-o tracker.ps

--output-txt

Write an accompanying text table to a file. Default: none (no text output).

--output-txt tracker.txt

--cgi

Read all parameters from environment variables (CGI mode) instead of the command line. Same as ephemeris. Default: off.

Viewer command

Generate a planet viewer PostScript diagram showing the planet, its moons, rings, and optional stars.

ephemeris-tools viewer [options]

Example:

ephemeris-tools viewer --planet saturn --time "2025-01-01 12:00" \
    --fov 0.1 --fov-unit deg --moons mimas enceladus titan \
    --center body -o view.ps --output-txt fov_table.txt

Planet and time

--planet

Same as ephemeris. Default: 6 (Saturn).

--time

Observation time as a date/time string. Default: "" (required).

--time "2025-06-15 03:30"

--ephem

Same as ephemeris. Default: 0.

Field of view

--fov

Field of view size (in units given by --fov-unit). Default: when omitted, 1.0 degrees is used (--fov-unit is then ignored).

--fov 0.05

--fov-unit

Unit for --fov. Accepts angle units (deg, arcmin, arcsec, mrad, urad), km, <planet> radii (e.g. Saturn radii), or an instrument FOV name (e.g. Cassini ISS narrow). See Argument reference for the full list. Default: deg (used only when --fov is given).

--fov 30 --fov-unit arcmin

Diagram center

--center

What the diagram is centered on. Values: body, ansa, J2000, star. Default: when omitted, the diagram is centered on the planet (same as body with no body name).

--center body
--center ansa
--center J2000

--center-body

Body name when --center is body. Default: when empty or omitted, the planet itself is used.

--center body --center-body titan

--center-ansa

Ring ansa name when --center is ansa. Default: when empty or omitted, a planet-specific ring is used (e.g. A Ring for Saturn, Main Ring for Jupiter, Epsilon Ring for Uranus, Adams Ring for Neptune; see the code for the full mapping).

--center ansa --center-ansa "A ring"

--center-ew

East or west ansa when --center is ansa. Default: east.

--center ansa --center-ew west

--center-ra

Right ascension in degrees for J2000 centering. Default: 0.0.

--center J2000 --center-ra 180.0 --center-dec -20.0

--center-dec

Declination in degrees for J2000 centering. Default: 0.0.

--center-ra-type

RA input format. Default: hours.

--center-ra-type degrees

--center-star

Star name when --center is star. Default: when empty or omitted with --center star, the diagram is centered on the planet (same as body).

--center star --center-star "delta Sco"

Observer position

The observer arguments --observer, --viewpoint, --observatory, --latitude, --longitude, --lon-dir, --altitude, and --sc-trajectory are the same as ephemeris with identical defaults.

Moons, rings, and stars

--moons

Moons to display. Same format as ephemeris. Default: when not specified, all moons in the planet configuration are shown.

--moons mimas enceladus titan

--moremoons

Flag: when present, also display all irregular moons for the planet in addition to the moons selected by --moons. Takes no value. See Additional moons (--moremoons) for details.

--rings

Ring display option codes or case-insensitive names (planet-specific). Integers and names can be mixed; see Argument reference for the full list. Default: none.

--rings main ge
--rings 61 62

--standard-star-catalog

Flag: overlay the standard star catalog for the planet (from the planet’s starlist file). Omit for no overlay.

--additional-star

Flag: overlay a user-specified star. When given, also provide --extra-ra and --extra-dec (and optionally --extra-name, --extra-ra-type). Omit for no additional star.

--extra-name

Name for a user-specified extra star. Default: none.

--extra-ra

Right ascension for the extra star (string, parsed per --extra-ra-type). Default: none.

--extra-ra-type

RA format for the extra star (e.g. hours, degrees). Default: none.

--extra-dec

Declination for the extra star. Default: none.

--other

Other bodies to overlay (list of strings, e.g. additional asteroid names). Default: none.

Plot options

--title

Diagram title string. Default: "" (no title).

--title "Saturn Jan 2025"

--labels

Moon (and star) label size. Only the size word is required: small, medium, or large (case-insensitive). Full CGI strings like Small (6 points) are also accepted. Default: Small (6 points) when not specified.

--moonpts

Moon marker enlargement in points. Default: 0 when not specified.

--blank-disks

Flag: blank (white-out) planet and moon disks. Omit for normal disks.

--ring-opacity

Ring plot type (Saturn only). Controls how rings are rendered. Values: Transparent, Semi-transparent (2x file size), Opaque. Default: Transparent when not specified.

--ring-pericenter-markers

Pericenter markers (Saturn and Uranus only). Saturn: None, F Ring. Uranus: None, Epsilon Ring only, All rings. Default: None when not specified.

--ring-pericenter-size

Pericenter marker size in points (Saturn and Uranus). Default: 4 when not specified.

--meridians

Flag: show prime meridians. Omit to hide.

--neptune-arc-model

Neptune ring arc motion model (Neptune only). Values: #1 (820.1194 deg/day), #2 (820.1118 deg/day), #3 (820.1121 deg/day). Default: not set when not specified.

--neptune-arc-thickness

Neptune arc weight in points (line thickness). Default: 4 when not specified.

Output

-o / --output

Write the PostScript diagram to a file. Default: none (no PS output).

-o view.ps

--output-txt

Write a field-of-view table to a file (body positions within the FOV). Default: none (no text output).

--output-txt fov_table.txt

Io torus (Jupiter only)

--io-torus: Flag: show the Io plasma torus (Jupiter only). Omit to hide.
--io-torus-inc: Io torus inclination in degrees. Default: 6.8.
--io-torus-rad: Io torus radius in km. Default: 422000.0.

Display-string overrides (CGI passthrough)

--ephem-display: Override the ephemeris description shown in the Input Parameters section (e.g. NEP095 + DE440). Default: auto-generated.
--moons-display: Override the moon selection description shown in the Input Parameters section (e.g. 802 Triton & Nereid). Default: auto-generated.
--rings-display: Override the ring selection description shown in the Input Parameters section (e.g. LeVerrier, Arago). Default: auto-generated.
--cgi: Read all parameters from environment variables (CGI mode) instead of the command line. Same as ephemeris. Default: off.

Environment / CGI mode

When running behind a CGI web server, set REQUEST_METHOD=GET and pass parameters via QUERY_STRING (or as individual environment variables). Use --cgi on any subcommand so parameters are read from the environment instead of the command line. When --cgi is not given, environment variables listed below are not used and do not override command-line arguments.

All CGI environment variables read by each tool:

Ephemeris (ephemeris-tools ephemeris --cgi): NPLANET, start, stop (or START_TIME/STOP_TIME), interval, time_unit, ephem, viewpoint, observatory, latitude, longitude, lon_dir, altitude, sc_trajectory, columns, mooncols, moons, EPHEM_FILE.

Tracker (ephemeris-tools tracker --cgi): NPLANET, start, stop, interval, time_unit, ephem, viewpoint, observatory, latitude, longitude, lon_dir, altitude, sc_trajectory, moons, rings, xrange, xunit, title, TRACKER_POSTFILE, TRACKER_TEXTFILE.

Viewer (ephemeris-tools viewer --cgi): NPLANET, time, fov, fov_unit, center, center_body, center_ansa, center_ew, center_ra, center_ra_type, center_dec, center_star, viewpoint, observatory, latitude, longitude, lon_dir, altitude, moons (or moremoons), rings, blank, meridians, opacity, peris, peripts, arcmodel, arcpts, other, labels, moonpts, title, standard, additional, extra_name, extra_ra, extra_ra_type, extra_dec, ephem, torus, torus_inc, torus_rad, VIEWER_POSTFILE, VIEWER_TEXTFILE.

See the Developer’s Guide CGI Parameter Reference for possible values and per-tool details. See Argument reference for column IDs, moon names, and observatory/spacecraft names.