pcal

pcal is a fast, dependency-free terminal calendar for the Shahanshahi (Imperial Persian) calendar, inspired by the Unix cal command.

The Shahanshahi calendar shares the months and leap-year rules of the Solar Hijri (Jalali) calendar but counts years from the founding of the Persian Empire by Cyrus the Great — an offset of +1180 over Jalali (Jalali 1404 = Shahanshahi 2584).

This documentation is for pcal dev. See the releases for downloads, or try it live at pcal.nl.

Highlights

• Single-month, three-month (-3), N-month (-n) and full-year (-y) views.
• Today highlighted in reverse video.
• Day-of-year (“Julian”) numbering with -j.
• Full Persian-script mode (--persian / --fa): Persian month and weekday names and Eastern-Arabic digits, with correct bidirectional rendering.
• Month input by number (5), romanized name (mordad), or Persian script (مرداد).
• Week starts on Saturday, following Iranian convention.
• Honors --no-color and the NO_COLOR environment variable.
• Ships a man page and bash/zsh/fish completions. No runtime dependencies.

Continue to Installation to get started, or jump to the CLI reference generated directly from the source.

Installation

pcal is headed to the major package managers. Until those land, prebuilt binaries are available from the releases page — each release also ships a SHA256SUMS file for integrity verification.

Package managers (coming soon)

# macOS
brew install pcal                          # Homebrew
sudo port install pcal                     # MacPorts

# Linux
sudo apt install pcal                      # Debian & Ubuntu
sudo dnf install pcal                      # Fedora & RHEL
yay -S pcal                                # Arch (AUR)
sudo zypper install pcal                   # openSUSE
sudo snap install pcal                     # Snap
flatpak install flathub nl.pcal.pcal       # Flatpak
nix profile install nixpkgs#pcal           # Nix

# Windows
winget install pcal                        # winget
scoop install pcal                         # Scoop
choco install pcal                         # Chocolatey

Prebuilt binaries (available now)

Download the package for your platform from the releases page, then install it:

# Debian / Ubuntu
sudo dpkg -i pcal_*_amd64.deb

# Fedora / RHEL
sudo dnf install ./pcal-*.x86_64.rpm

# Or extract the tarball and put `pcal` on your PATH
tar xzf pcal-*-linux-x86_64.tar.gz

Each archive also contains the man page and bash/zsh/fish completions.

Usage

pcal [OPTIONS] [MONTH] [YEAR]

By default pcal prints the current month. Positional arguments select a specific month and/or year; flags change the view.

Positional arguments

How arguments are interpreted:

• pcal → current month.
• pcal 5 → month 5 (Mordad) of the current year — a single value that parses as a month is treated as a month.
• pcal 2585 → the whole year 2585 — a single value that is not a valid month is treated as a year.
• pcal mordad 2585 / pcal 5 2585 → Mordad 2585.

Options

The week starts on Saturday (Sa Su Mo Tu We Th Fr), and today is highlighted in reverse video. For the exact, always-current option list see the CLI reference.

Examples

Live, colored versions of these run on pcal.nl. Below is the plain text each command prints.

Current month

$ pcal
      Tir 2585
Sa Su Mo Tu We Th Fr
       1  2  3  4  5
 6  7  8  9 10 11 12
13 14 15 16 17 18 19
20 21 22 23 24 25 26
27 28 29 30 31

(The current day is highlighted in reverse video.)

Three months side by side

$ pcal -3

Shows the previous, current, and next month in a row — handy for planning across a month boundary.

A full year

$ pcal -y 2585

Prints all twelve months of 2585 in a three-column grid.

A specific month

$ pcal mordad 2585     # or: pcal 5 2585
     Mordad 2585
Sa Su Mo Tu We Th Fr
            1  2  3
 4  5  6  7  8  9 10
11 12 13 14 15 16 17
18 19 20 21 22 23 24
25 26 27 28 29 30 31

Day-of-year numbering

$ pcal -j 1 2585

Replaces each day-of-month with its ordinal day-of-year (1–365/366).

Persian script

$ pcal --persian 1 2585
     فروردین ۲۵۸۵
 ش  ی  د  س  چ  پ  ج
                   ۱
 ۲  ۳  ۴  ۵  ۶  ۷  ۸
 ۹ ۱۰ ۱۱ ۱۲ ۱۳ ۱۴ ۱۵
۱۶ ۱۷ ۱۸ ۱۹ ۲۰ ۲۱ ۲۲
۲۳ ۲۴ ۲۵ ۲۶ ۲۷ ۲۸ ۲۹
۳۰ ۳۱

Month and weekday names and digits switch to Persian, while the grid stays left-to-right.

Command-Line Help for pcal

This document contains the help content for the pcal command-line program.

Command Overview:

• pcal↴

pcal

A Shahanshahi (Imperial Persian) calendar for the terminal.

Displays the current month by default. Accepts an optional month and year to show a specific month, or just a year to show all 12 months. Years are counted from the founding of the Persian Empire by Cyrus the Great.

Usage: pcal [OPTIONS] [MONTH] [YEAR]

EXAMPLES: pcal Show current month pcal 2584 Show all months of year 2584 pcal mordad 2584 Show Mordad (month 5) of 2584 pcal 5 2584 Same as above, by number pcal -3 Show previous, current, and next month pcal –persian Use Persian script and digits

Arguments:

• <MONTH> — Month number (1-12) or name (farvardin, mordad, مرداد, …)
• <YEAR> — Shahanshahi year, e.g. 2584

Options:

• -3 — Display the previous, current, and next month side by side
• -y, --year-view — Display all 12 months of the year
• -n <NUM> — Display the next NUM months starting from the current month
• -j — Display day-of-year numbers instead of day-of-month
• --persian — Use Persian script (month names, weekday names, and digits)
• --no-color — Disable colored output (also respects NO_COLOR env variable)

This document was generated automatically by clap-markdown.

API documentation

pcal is a small library + binary crate. The rustdoc API documentation for the library modules (shahanshahi, calendar, persian, display, formatter, cli) is built with cargo doc and bundled alongside this guide.

➡️ Open the API docs

These are regenerated on every release from the source, so they always match the published version.