README.md

@@ -152,4 +152,24 @@ Output:
 
 ![cli.svg](images/cli.svg)
 
+## Perl Script
+
+A Perl script is available in the `bin` directory to provide a command-line interface for the Baha'i Date API.
+
+### Usage
+
+`./bin/badi-date.pl [options]`
+
+### Options
+
+- `--today`: Get today's Badi date.
+- `--date <YYYY-MM-DD>`: Get the Badi date for a specific date.
+- `--progress`: Show the progress of the current Badi date.
+
+### Examples
+
+`./bin/badi-date.pl --today`
+`./bin/badi-date.pl --date 2024-01-01`
+`./bin/badi-date.pl --progress`
+
 # Last Update: Dec 28, 2025

bin/badi-date.pl

@@ -0,0 +1,79 @@
+#!/usr/bin/env perl
+
+use strict;
+use warnings;
+use Getopt::Long;
+use JSON;
+use POSIX;
+use Data::Dumper;
+
+# Check for gum
+if (!-x "/usr/bin/gum") {
+    print STDERR "Error: gum is not installed. Please install it to continue.\n";
+    print STDERR "Installation instructions for popular Linux distributions:\n";
+    print STDERR "  Ubuntu/Debian: sudo apt install gum\n";
+    print STDERR "  Fedora: sudo dnf install gum\n";
+    print STDERR "  Arch Linux: sudo pacman -S gum\n";
+    print STDERR "  CentOS/RHEL: sudo yum install gum\n";
+    print STDERR "  openSUSE: sudo zypper install gum\n";
+    print STDERR "  Gentoo: sudo emerge gum\n";
+    print STDERR "  Alpine: sudo apk add gum\n";
+    print STDERR "  NixOS: nix-env -iA nixpkgs.gum\n";
+    exit 1;
+}
+
+my $today;
+my $date;
+my $progress;
+
+GetOptions(
+    'today' => \$today,
+    'date=s' => \$date,
+    'progress' => \$progress,
+);
+
+if ($today) {
+    my $json_string = `curl -s http://localhost:1844/today?timezoneId=America/New_York`;
+    my $json = decode_json($json_string);
+    my $message = $json->{'message'};
+    $message =~ s/<[^>]*>//g;
+    system("gum style --foreground 212 '$message'");
+}
+elsif ($date) {
+    my ($year, $month, $day) = split('-', $date);
+    my $json_string = `curl -s "http://localhost:1844/date?year=$year&month=$month&day=$day&timezoneId=America/New_York"`;
+    my $json = decode_json($json_string);
+    my $message = $json->{'message'};
+    $message =~ s/<[^>]*>//g;
+    system("gum style --foreground 212 '$message'");
+}
+elsif ($progress) {
+    my $json_string = `curl -s http://localhost:1844/today?timezoneId=America/New_York`;
+    my $json = decode_json($json_string);
+    my $badi_date = $json->{'badi_date'};
+
+    my $day_of_month = $badi_date->{'day'};
+    my $month_of_year = $badi_date->{'month'};
+    my $year_of_vahid = ($badi_date->{'year'} - 1) % 19 + 1;
+    my $vahid_of_kull_i_shay = floor(($badi_date->{'year'} - 1) / 19) + 1;
+    my $year_of_kull_i_shay = $badi_date->{'year'};
+
+    my $day_progress = "█" x $day_of_month . " " x (19 - $day_of_month);
+    my $month_progress = "█" x $month_of_year . " " x (19 - $month_of_year);
+    my $vahid_progress = "█" x $year_of_vahid . " " x (19 - $year_of_vahid);
+    my $kull_i_shay_vahid_progress = "█" x $vahid_of_kull_i_shay . " " x (19 - $vahid_of_kull_i_shay);
+    my $kull_i_shay_year_progress = "█" x int($year_of_kull_i_shay / 361 * 19) . " " x (19 - int($year_of_kull_i_shay / 361 * 19));
+
+
+    system("gum style --foreground 212 'Day of Month:     [$day_progress] $day_of_month/19'");
+    system("gum style --foreground 212 'Month of Year:    [$month_progress] $month_of_year/19'");
+    system("gum style --foreground 212 'Year of Vahid:    [$vahid_progress] $year_of_vahid/19'");
+    system("gum style --foreground 212 'Vahid of Kull-i-Shay: [$kull_i_shay_vahid_progress] $vahid_of_kull_i_shay/19'");
+    system("gum style --foreground 212 'Year of Kull-i-Shay: [$kull_i_shay_year_progress] $year_of_kull_i_shay/361'");
+}
+else {
+    # Default behavior: display today's date
+    # Or show help
+}
+
+1;