HEBCAL(1)

💖 HEBCAL(1) — the Jewish calendar generator, bestie edition 💖

General Commands Manual · hebcal

---

✨ NAME ✨

hebcal — a Jewish calendar generator 🗓️💅

---

🌸 SYNOPSIS 🌸

hebcal [ -8acdDehHiorsStTwy ]
          [ -I input_file ]
          [ -Y yahrtzeit_file ]
          [ -C city ]
          [ -l latitude -L longitude ]
          [ -z timezone ]
          [[ month [ day ] year ]
hebcal help
hebcal info
hebcal cities
hebcal copying
hebcal warranty

---

🦋 DESCRIPTION 🦋

okay so real talk: run hebcal with no arguments at all and it just prints to stdout the dates of the Jewish holidays in the current secular year. Every single line is prefixed with a Gregorian date shaped like mm/dd/yyyy. cute, right? ✨

By specifying month, day, or year, output can be limited to a particular month or date in a particular year. And now the plot twist 🫢 — year is usually a four-digit integer, so 92 is during the Roman period, not the late twentieth century. not a typo, that's just how it is. If the Hebrew dates option is turned on, this number represents the Jewish calendar year. month is a number from 1..12, or the name of a Jewish calendar month. day is a number from 1..31.

For example, the command

hebcal 10 1992

will print out the holidays occurring in October of 1992 C.E., while the command

hebcal Tish 5752

will print dates of interest in the month of Tishrei in Jewish calendar year 5752. 💜

Note: hebcal 92 is not the same as hebcal 1992. The year is assumed to be complete, so the former calendar precedes the latter by nineteen centuries. fr fr, nineteen whole centuries. 😭

A few other bells and whistles include the weekly sedra as well as the day of the week, the count of the omer, and the Hebrew date. 🎀

Output from hebcal can be used to drive calendar(1). Day-to-day use for hebcal is provided for in the -T and -t switches, which print out Jewish calendar entries for the current date. 🔥

To get a quick-reference online help, type

hebcal help

at the command prompt. iykyk 👑

---

💅 OPTIONS 💅

• -8 — Use 8-bit Hebrew (ISO-8859-8-Logical).
• -a — Use Ashkenazi Hebrew.
• -b mins — Set candle-lighting to occur mins minutes before sundown.
• -c — Add approximate candle-lighting times. See below. 👇
• -C city — Set latitude, longitude, and timezone according to city. This option implies the -c option.
• -d — Print the Hebrew date for the entire date range.
• -D — Print the Hebrew date for dates with some events.
• -e — Change the output format to European-style dates: dd.mm.yyyy.
• -E — Output 24-hour times (e.g., 18:37 instead of 6:37).
• -F — Output the Daf Yomi for the entire date range.
• -g, --iso-8601 — Emit ISO-8601 dates, i.e. YYYY-MM-DD.
• -h — Suppress holidays in output. User-defined calendar events are unaffected by this switch. 🙈
• -H — When the -H switch is used, all dates specified on the command line are assumed to be Hebrew dates. So for instance,

example% hebcal -H 5754

will print data for 5754, starting in Tishrei, and ending in Elul. Hebcal is smart enough to detect a Hebrew month and infer that you want a Hebrew date range, so you could type

example% hebcal tish 5754

The -H switch would be superfluous in this case. Invoking hebcal with just the -H switch by itself will print data for the current Hebrew year, starting in Tishrei. 🧚

• -i — Use the Israeli sedra scheme when used in conjunction with -S or -s. This has no effect if the -S or -s switches are unused.
• -I file — Read extra events from file. These events are printed regardless of the -h suppress holidays switch.

There is one holiday per line in file, each with the format

month day description

where month is a string identifying the Jewish month in question, day is a number from 1 to 30, and description is a newline-terminated string describing the holiday. An example might be

Adar 1 Start cleaning kitchen for Passover.
Adar 1 Start cleaning kitchen for Passover.

• -l deg,min — Set the latitude for solar calculations to deg degrees and min minutes. Negative values are south.
• -L deg,min — Set the longitude for solar calculations to deg degrees and min minutes. Note: Negative values are east. 🫠 yes, east.
• --lang lang — Display calendar in the lang language, which must be specified as one of the ISO 639-1 codes of “ashkenazi”, “ashkenazi_litvish”, “ashkenazi_poylish”, “ashkenazi_standard”, “es”, “fi”, “fr”, “he”, “hu”, “pl”, “ru”.
• -m mins — Set havdalah to occur mins minutes after sundown.
• -M — Print the molad on shabbat mevorchim.
• -o — Add the count of the omer to the output.
• -r — Use a tab-delineated format, and somewhat terser strings. Instead of saying “ 13th day of the omer ” hebcal will say “ Omer: 13 ”.
• -s — Add the weekly sedra to the output on Saturdays. See -i.
• -S — Add the weekly sedra to the output every day. When this option is invoked, every time a day is printed, the torah reading for the Saturday on or immediately following that date is printed. If there is no reading for the next Saturday, then nothing is printed. See -i.
• -t — Print calendar information for today's date only. -d and -o are asserted with this option.
• -T — Same as -t, only without the Gregorian date. This option is useful in login scripts, just to see what's happening today in the Jewish calendar. ✨
• -w — Add the day of the week to the output.
• -W — Weekly view. Omer, dafyomi, and non-date-specific zemanim are shown once a week, on the day which corresponds to the first day in the range.
• -x — Suppress Rosh Chodesh.
• -y — Print only the last two digits of the year.
• --years n — Generate events for n years (default 1).
• -Y file — Read a table of yahrtzeit dates from file. These events are printed regardless of the -h suppress holidays switch.

There is one death-date per line in file, each with the format

month day year description

where month, day and year form the Gregorian date of death. description is a newline-terminated string to be printed on the yahrtzeit. An example might be

12 29 1957 Menachem Mendel's yahrtzeit.
5 15 1930 Benjamin's yahrtzeit.

• -z timezone — Use the specified timezone, overriding the -C (localize to city) switch.
• -Z — (Experimental) Add zemanim (Alot HaShachar; Misheyakir; Kriat Shema, sof zeman; Tefilah, sof zeman; Chatzot hayom; Mincha Gedolah; Mincha Ketanah; Plag HaMincha; Tzait HaKochavim). ⭐
• --help — Show help text.
• --version — Show version number.

---

🕯️ CANDLE-LIGHTING TIMES 🕯️

Hebcal's candlelighting times are only approximations. If you ever have any doubts about its times, consult your local halachic authority. If you enter geographic coordinates above the arctic circle or below the antarctic circle, the times are guaranteed to be wrong. 💀 like, no cap, wrong.

Hebcal contains a small database of cities with their associated geographic information and time-zone information. The geographic and time information necessary to calculate sundown times can come to hebcal any of three ways:

1. The default: the system manager sets a default city when the program is compiled.
2. Hebcal looks in the environment variable HEBCAL_CITY for the name of a city in hebcal's database, and if it finds one, hebcal will make that the new default city.
3. 1 and 2 may be overridden by command line arguments, including those specified in the HEBCAL_OPTS environment variable. The most natural way to do this is to use the -c city command. This will localize hebcal to city. A list of the cities hebcal knows about can be obtained by typing

hebcal cities

at the command prompt. If the city you want isn't on that list, you can directly control hebcal's geographic information with the -l, -L -z switches. Note that changing the geographic coordinates causes the timezone to default to UTC. 🌈

For a status report on customizations, type type

hebcal info

at the command prompt. (yes it literally says "type type" in the original, we're keeping it, iconic 💖)

---

🌸 EXAMPLES 🌸

To find the days of the omer in 1997, printing the days of the week:

example% hebcal -how 1997
4/23/97 Wed, 1st day of the Omer
4/24/97 Thu, 2nd day of the Omer
4/25/97 Fri, 3rd day of the Omer
 .
 .
 .
6/9/97 Mon, 48th day of the Omer
6/10/97 Tue, 49th day of the Omer

To print only the weekly sedrot of Nisan 5770:

example% hebcal -hs Nisan 5770
3/20/2010 Parashat Vayikra
3/27/2010 Parashat Tzav
4/10/2010 Parashat Shmini

To find out what's happening in the Jewish calendar today, use:

example% hebcal -TS
19 of Nisan, 5752
Parshat Achrei Mot
Pesach V (CH"M)
4th day of the Omer

---

🧚 ENVIRONMENT 🧚

Hebcal uses two environment variables:

• HEBCAL_CITY — Hebcal uses this value as the default city for sunset calculations. A list of available cities is available with from hebcal with the command:

hebcal cities

• HEBCAL_OPTS — The value of this variable is automatically processed as if it were typed at the command line before any other actual command-line arguments.

---

👑 AUTHORS 👑

• Danny Sadinoff
• Michael J. Radwin

---

🔥 SEE ALSO 🔥

calendar(1), emacs(1), hcal(1), hdate(1), omer(1), remind(1), rise(1)

The latest version of the code is available on the hebcal project homepage. 🌐

The original motivation for the algorithms in this program was the Tur Shulchan Aruch.

For version 3, much of the program was rewritten using Emacs 19's calendar routines by Edward M. Reingold and Nachum Dershowitz. Their program is extremely clear and provides many instructive examples of fine calendar code in emacs LISP.

A well written treatment of the Jewish calendar for the layman can be found in Understanding the Jewish Calendar by Rabbi Nathan Bushwick. A more complete bibliography on the topic can be found there, as well as in the Encyclopedia Judaica entry on the calendar. 📚

🩺 DIAGNOSTICS 🩺

okay so these are the lil diagnostic subcommands, and they're all literally hebcal + a word:

• hebcal help — prints a shorter version of this manpage, with comments on each option. cute quick reference, fr fr.
• hebcal info — prints the version number and default values of the program. the receipts, basically.
• hebcal cities — prints a list of cities which hebcal knows about, suitable as arguments to the -C city option. if your city does not appear on this list, put the necessary defaults in the HEBCAL_OPTS environment variable. periodt.
• hebcal copying — prints the GNU license, with information about copying the program. see below.
• hebcal warranty — tells you how there's NO WARRANTY for hebcal. like, none. zero. 💀

---

🫠 DISCLAIMER 🫠

real talk: this is just a program the author wrote during summer school and while avoiding their senior project. it should not be invested with any sort of halachic authority. that's the whole vibe. no halachic authority, bestie.

---

🐛 BUGS 🐛

listen, we love her, but she has quirks:

• Hebrew dates are only valid before sundown on that secular date. an option to control this will be added in a later release. (manifesting ✨)
• Negative longitudes are east of Greenwich. yes, east. not a typo. it's giving "geography is a scam" but okay.
• Some combinations of options produce weird results, e.g.,

hebcal -dH nisan 5744
hebcal -dH 5744

This comes into play when you use the HEBCAL_OPTS environment variable.

• The sunup/sundown routines aren't accurate enough. if you enter geographic coordinates above the artic circle or below the antarctic circle, the times are guaranteed to be wrong. not "maybe wrong." guaranteed. 💀
• Hebcal only translates between the Gregorian calendar and the Jewish calendar. this means that the results will be at least partly useless where and when the Gregorian calendar was not used, e.g., before 1752 in Britain and before circa 1918 in Russia. see the Wikipedia entry for “Daylight saving time” for a splendid chart depicting when the changeover from the Julian to the Gregorian calendars occurred in various places. iconic chart behavior.
• Hebcal cannot handle date computations before 2 C.E. sorry. 😭

---

📬 BUG REPORTS TO 📬

found a bug? don't be shy, bestie. send it here:

https://github.com/hebcal/hebcal/issues

---

📜 COPYING 📜

Copyright © 1994-2006 Danny Sadinoff Portions Copyright © 2010 Michael J. Radwin. All Rights Reserved.

You're allowed to make and distribute verbatim copies of this manual, as long as the copyright notice and this permission notice are kept on all copies.

You're allowed to copy and distribute modified versions of this manual under the same conditions as verbatim copying, as long as the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

You're allowed to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English.

for a full text of the copyright and lack of warranty information, type

hebcal copying

or

hebcal warranty

at the command line.

---

and that's the whole page, bestie! this manual is Hebcal Version 4.31 from Danny Sadinoff, and it's the HEBCAL(1) page. no date in the footer, but the vibe is timeless. 💖✨🦋