Tới nội dung

Mã và dữ liệu mở

Tài liệu API

Cách gọi năm gói JavaScript và gói Python của Nhật Nguyệt bằng lớp API tiếng Anh: tham số đặt tên, giờ đồng hồ, kết quả theo ngôn ngữ. Kết quả in dưới mã là kết quả thật.

Cài đặt

# JavaScript, TypeScript
npm install @nhatnguyet/lunar @nhatnguyet/ziwei
npm install @nhatnguyet/bazi @nhatnguyet/numerology @nhatnguyet/festivals
# cùng mã dưới tên Việt: am-lich, tu-vi, bat-tu, than-so-hoc, le-hoi
# Python
pip install nhatnguyet

Mỗi gói giữ nguyên các hàm gốc đặt tên tiếng Việt (lapLaSoTuVi, solarToLunar...) và có thêm một lớp API tiếng Anh song song, tham số đặt tên:

  • ngày viết "YYYY-MM-DD", { year, month, day } hay một Date (đọc theo giờ máy);
  • giờ đồng hồ viết "HH:MM" (24 giờ); gói tự đổi sang canh giờ (giờ Tý từ 23:00 tới 00:59);
  • giới tính là "male" / "female";
  • lang: "en" | "vi" | "zh" (mặc định "en") cho mọi tên trong kết quả;
  • terms: "pinyin" | "han" | "vi" (chỉ áp cho tiếng Anh, xem dưới);
  • đối tượng gốc giữ nguyên ở raw, nên không mất gì.

Thiên can, địa chi và tứ hóa: terms

Mười thiên can, mười hai địa chi, các cặp can chi, tứ hóa và hai dấu Tuần, Triệt không có tên dịch sang tiếng Anh. Với lang: "en", tham số terms quyết định cách viết chúng:

termscan, chicặp can chitứ hóaTuần, Triệt
"pinyin" (mặc định)Geng, WuGeng WuHua Lu, Hua Quan, Hua Ke, Hua JiXun Kong, Jie Kong
"han"庚, 午庚午化禄, 化权, 化科, 化忌旬空, 截空
"vi"Canh, NgọCanh NgọHóa Lộc, Hóa Quyền, Hóa Khoa, Hóa KỵTuần, Triệt

Pinyin viết không dấu thanh, như sách Bát Tự, Tử Vi tiếng Anh vẫn viết, nên 戊 và 午 đều là "Wu", 己 và 忌 đều là "Ji"; khi cần phân biệt thì chọn "han". "vi" cho tên Hán Việt như in trong lịch Việt Nam (đầu ra của phiên bản 0.2.0). Mọi thứ đã có tên tiếng Anh (ngũ hành, con giáp, tiết khí, cung, sao, tên cách cục, thập thần, vòng trường sinh) đều viết tiếng Anh dù terms là gì, và chữ tiếng Anh không bao giờ mang một từ tiếng Việt (một test soi mọi ca kiểm để tìm chữ cái tiếng Việt). lang: "vi" luôn là tiếng Việt, lang: "zh" luôn là chữ Hán. Mã giữ nguyên ở mọi ngôn ngữ: nameVi, code (sao lưu niên), id (lễ hội). Các giá trị liệt kê cũng là mã tiếng Anh ở mọi lang: gender (male, female), kind và group của sao Tử Vi, toYearPalace, toMinorLimit và toDecade của sao lưu niên (same-palace, opposite, trine, hoặc ""), luck.direction của Bát Tự (forward, backward) và symbolicStars[].pillars (year, month, day, hour), kind của tiết khí (jie, qi), cùng calendar, group và scope của lễ hội.

TypeScript và Python trả cùng một bộ khoá (camelCase), hai lệnh dòng lệnh in ra cùng từng byte. Mọi kết quả dưới đây đều do chạy chính đoạn mã ấy mà ra.

Âm lịch: @nhatnguyet/am-lich

import { toLunar, toSolar, solarTerms, dayPillar, hourBranch } from "@nhatnguyet/am-lich";

toLunar("2027-02-06");
// {"year":2027,"month":1,"day":1,"leap":false,"solarDate":"2027-02-06","country":"VN","timeZone":7,
//  "yearName":"Ding Wei","monthName":"Ren Yin","dayName":"Bing Chen","zodiac":"Goat",
//  "solarTerm":"Start of Spring","lang":"en"}
toLunar("2027-02-06", { terms: "han" }).yearName;   // "丁未"

toLunar("1985-01-21", { country: "CN", lang: "zh" });   // Tết 1985: Vietnam and China differ
// {"year":1984,"month":12,"day":1,"leap":false,"solarDate":"1985-01-21","country":"CN","timeZone":8,
//  "yearName":"甲子","monthName":"丁丑","dayName":"庚申","zodiac":"鼠","solarTerm":"大寒","lang":"zh"}

toSolar({ year: 2023, month: 2, day: 1, leap: true });
// {"day":22,"month":3,"year":2023,"date":"2023-03-22"}
// A lunar date that does not exist (no such leap month, day 30 of a 29-day month) throws RangeError.

solarTerms(2027, { country: "CN" })[2];
// {"index":21,"longitude":315,"name":"Start of Spring","nameVi":"Lập Xuân","kind":"jie",
//  "date":"2027-02-04","time":"09:46","timeZone":8}

dayPillar("1990-09-19");
// {"label":"Ding Hai","stem":"Ding","branch":"Hai","stemIndex":3,"branchIndex":11,"stemElement":"Fire",
//  "branchElement":"Water","naYin":"Earth on the Roof","naYinElement":"Earth"}

hourBranch("23:30");
// {"index":0,"name":"Zi","animal":"Rat","range":"23:00-00:59"}

Giờ hoàng đạo: auspiciousHours

Mười hai canh giờ của một ngày, mỗi canh giờ ghi là giờ hoàng đạo hay giờ hắc đạo, kèm vị thần cai quản, như lịch Việt Nam vẫn in. Ngày nào cũng có sáu giờ hoàng đạo; là sáu giờ nào thì chỉ tùy địa chi của ngày. Các thần đi vòng bắt đầu từ Thanh Long (Qing Long), khởi ở một giờ định theo cặp địa chi xung nhau chứa chi của ngày; các thần hoàng đạo là số 0, 1, 4, 5, 7 và 10 của vòng (AUSPICIOUS_SPIRITS). Khoảng giờ đồng hồ tính theo giờ Việt Nam. spirit theo terms như can chi: mặc định là pinyin, "han" cho chữ Hán, "vi" cho tên tiếng Việt (thần thứ sáu, 宝光 Bao Guang trong bảng giờ của sách, là Kim Đường trong lịch Việt Nam).

import { auspiciousHours } from "@nhatnguyet/am-lich";

auspiciousHours("2027-02-06").day;   // "Bing Chen"
auspiciousHours("2027-02-06").hours[4];
// {"index":4,"branch":"Chen","animal":"Dragon","range":"07:00-08:59","auspicious":true,
//  "spirit":"Qing Long","spiritIndex":0}
auspiciousHours("2027-02-06").hours.filter((h) => h.auspicious).map((h) => h.range);
// ["03:00-04:59","07:00-08:59","09:00-10:59","15:00-16:59","17:00-18:59","21:00-22:59"]
auspiciousHours("2027-02-06", { lang: "zh" }).hours[9].spirit;   // "宝光"

Kết quả được đối chiếu với lõi tính gốc trên 1.096 ca kiểm (ca-kiem/auspicious-hours.json). Python auspicious_hours(date, lang=..., terms=...), dòng lệnh nhatnguyet hours 2027-02-06, công cụ MCP auspicious_hours.

country nhận VN (mặc định, UTC+7), CN, TW, HK, MO, SG, MY, ID, PH (UTC+8), KR, JP (UTC+9); cùng một quy tắc, chỉ khác giờ địa phương dùng để định ngày. timeZone đặt đè lên nó. Con giáp thứ tư của Việt Nam là Mèo, các nước khác là Thỏ. Ngoài ra còn: solarTermOn(date), yearPillar(lunarYear), solarTermNames(), parseDate, parseTime, stemBranchName(label, lang, terms), termName(vi, lang, terms).

Tử Vi: @nhatnguyet/tu-vi

import { castZiWei, decadeLuck, yearlyLuck, yearlyStars, findPatterns, ziWeiSvg } from "@nhatnguyet/tu-vi";

const chart = castZiWei({ date: "1990-09-19", time: "20:00", gender: "male", viewYear: 2026 });
chart.hour;     // {"index":10,"name":"Xu","animal":"Dog","range":"19:00-20:59"}
chart.lunar;    // {"year":1990,"month":8,"day":1,"leap":false}
chart.bureau;   // {"number":5,"name":"Earth Five"}
chart.yinYang;  // "Yang Male"
chart.palaces[chart.lifePalace];
// {"index":11,"branch":"Hai","stemBranch":"Ding Hai","name":"Life Palace","nameVi":"Mệnh","isLife":true,
//  "isBody":false,"tuan":true,"triet":false,"stars":[{"name":"Moon","nameVi":"Thái Âm","kind":"major",
//  "brightness":"Exalted","transformation":"Hua Ji"},{"name":"Left Assistant","nameVi":"Tả Phù","kind":"minor",
//  "group":"auspicious"}, ...]}

decadeLuck(chart)[3];
// {"order":4,"palaceIndex":2,"branch":"Yin","palace":"Property","fromAge":35,"toAge":44,
//  "fromYear":2024,"toYear":2033,"majorStars":["Military Song","Celestial Minister"]}
yearlyLuck(chart).decade;       // {"fromAge":35,"toAge":44,"palace":"Property"}
findPatterns(chart)[1];
// {"name":"Left and Right Assistants Meeting","nameVi":"Tả Hữu đồng hội","condition":"Left Assistant and
//  Right Assistant both gather in the triangle and opposite of the Life palace", ...,"nameHan":"左右同會"}
chart.toSvg({ theme: "dark" }); // "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1000 10..."

const han = castZiWei({ date: "1990-09-19", time: "20:00", gender: "male", terms: "han" });
han.palaces[han.lifePalace].stemBranch;                // "丁亥"
han.palaces[han.lifePalace].stars[0].transformation;   // "化忌"
  • Bắt buộc có time hay hourBranch (0 = Tý ... 11 = Hợi); hai giá trị không khớp nhau thì báo lỗi.
  • Sinh từ 23:00 tới nửa đêm thì giữ đúng ngày đã nhập (có sách tính sang ngày hôm sau; muốn theo cách ấy thì nhập ngày hôm sau). Lá số ghi rõ điều này ở notes.
  • Tuổi là tuổi mụ (sinh ra là 1 tuổi); fromYear/toYear cho năm dương tương ứng.
  • palaces đánh số theo địa chi, 0 (Tý) tới 11 (Hợi); kind là major, minor, growth (vòng Tràng Sinh), year-ring (vòng Thái Tuế) hay scholar (vòng Bác Sỹ).
  • Phụ tinh mang group: malefic (lục sát tinh: Kình Dương, Đà La, Địa Không, Địa Kiếp, Hỏa Tinh, Linh Tinh), auspicious (lục cát tinh cùng Lộc Tồn và Thiên Mã) hay miscellaneous (mọi phụ tinh khác). Lá số thô giữ mã của lõi tính ở nhom; bảng đổi mã là STAR_GROUP_EN.
  • Mã của yearlyStars là yearly-taisui, yearly-lucun, yearly-qingyang, yearly-tuoluo, yearly-tianma (YEARLY_STAR_CODE_EN; trường ma thô giữ mã của lõi tính).
  • schools đổi quy tắc ở những chỗ các sách không thống nhất (Hỏa Tinh và Linh Tinh, tháng nhuận, tứ hóa của can Canh, Thiên Trù, Thiên Thương và Thiên Sứ); mặc định không đổi. Xem schools.md: castZiWei({ ..., schools: { fireBell: "quanshu", leapMonth: "split-at-15" } }). Khi ấy lá số mang schools (chỉ các lựa chọn khác mặc định) và một dòng trong notes.
  • country (như ở toLunar: mặc định "VN", "CN", "KR", "JP"...) hay timeZone (số giờ) cho biết lịch âm của nước nào đổi ngày sinh thành ngày âm để lập lá số. Lịch các nước khác nhau ở một số ngày: sinh 1985-01-21, lịch Việt Nam cho mùng 1 tháng Giêng năm Ất Sửu, country: "CN" cho mùng 1 tháng Chạp năm Giáp Tý, nên ra lá số khác. Lá số không theo UTC+7 mang khoá timeZone và ghi rõ trong notes; Python cast_zi_wei(..., country="CN") hay time_zone=8, dòng lệnh nhatnguyet ziwei 1985-01-21 10:00 male --country CN.
  • Tên cách cục là tên tiếng Anh dịch từ tên chữ Hán, tên trong sách nằm ở nameHan (terms: "vi" giữ tên Hán Việt); lang: "zh" cho 命宫, 太阴, 化忌, 土五局.
  • Tên sao theo cách gọi quen dùng trong sách Tử Vi tiếng Anh; ba tên khác với bảng của lõi tính Go: 陀羅 Spinning Top, 天相 Celestial Minister, 天鉞 Celestial Halberd (STAR_EN_FIX).
  • ziWeiSvg(chart, { theme, width, lang }) và chart.toSvg() vẽ ra cùng một SVG với renderChartSvg(chart.raw). toSvg không liệt kê được, nên không bao giờ lọt vào JSON.

Tra cứu và vận hạn

castZiWei trả lá số kèm các hàm tra cứu (không liệt kê được, nên JSON không đổi); các hàm ấy cũng có bản đứng riêng, nhận lá số từ castZiWei hay lapLaSoTuVi. Cung cho bằng chỉ số (0 = Tý) hay bằng tên tiếng Anh, tiếng Việt, tiếng Trung (không phân biệt hoa thường); sao cho bằng tên ở bất kỳ thứ tiếng nào trong ba.

import { castZiWei, horoscope, surroundingPalaces, flyingTransformations, fliesTo, selfTransformed, palaceIsEmpty } from "@nhatnguyet/tu-vi";

const chart = castZiWei({ date: "1990-09-19", time: "20:00", gender: "male" });
chart.palace("命宫").name;              // "Life Palace"
chart.star("Purple Star").palace.name;  // "Health"
surroundingPalaces(chart, "Life Palace");
// target "Life Palace", opposite "Travel", wealth "Wealth", career "Career"
flyingTransformations(chart, "Life Palace")[0];
// {"type":"Hua Lu","star":"Moon","palaceIndex":11,"palace":"Life Palace","self":true}
fliesTo(chart, "Life Palace", "Travel", "ji");  // false
selfTransformed(chart, "Life Palace");          // true
palaceIsEmpty(chart, "Spouse");                 // true (no major star)

const h = chart.horoscope({ date: "2026-11-19" });   // same as horoscope(chart, { date })
h.lunar;  // {"year":2026,"month":10,"day":11,"leap":false}
h.age;    // 37
h.decade;
// {"palaceIndex":2,"branch":"Yin","palace":"Property","stemBranch":"Wu Yin","palaceNames":[...],
//  "transformations":[{"type":"Hua Lu","star":"Greedy Wolf","palaceIndex":0,"palace":"Parents"}, ...],
//  "fromAge":35,"toAge":44}
h.minorLimit;  // {"palaceIndex":4,"branch":"Chen","palace":"Friends/Subordinates","stemBranch":"Geng Chen", ...}
h.year;
// {"palaceIndex":6,"branch":"Wu","palace":"Health","stemBranch":"Bing Wu","palaceNames":[...],
//  "transformations":[..., {"type":"Hua Ji","star":"Purity","palaceIndex":10,"palace":"Siblings"}],
//  "year":2026,"stars":[{"code":"yearly-taisui", ...}, {"code":"yearly-lucun","name":"Yearly Prosperity",
//  "byStem":true,"palaceIndex":5,"branch":"Si","palace":"Travel", ...}, ...]}
h.month;  // {"palaceIndex":6,"branch":"Wu","palace":"Health","stemBranch":"Ji Hai","palaceNames":[...],"transformations":[],"month":10}
h.year.palaceNames.slice(4, 8);  // ["Spouse","Siblings","Life Palace","Parents"]: index 6 (Ngọ) is the year's Life palace
h.day;    // null
h.hour;   // null
chart.horoscope({ date: "1991-03-01" }).decade;  // null: before the first ten-year period
  • Mọi giá trị đều lấy từ lõi tính: decade từ đại vận (decadeLuck), minorLimit, year và month từ yearlyLuck (tiểu hạn, cung lưu niên, tứ hóa của năm, cung lưu nguyệt theo phép Đẩu Quân), year.stars từ yearlyStars.
  • transformations của đại vận và tiểu hạn là tứ hóa theo can của cung, lấy từ bảng tứ hóa của lõi tính, cùng bảng với các đường phi tinh của flyingTransformations, fliesTo, selfTransformed. month.transformations rỗng: lõi tính không có tứ hóa theo tháng.
  • palaceNames (chỉ số 0 = Tý) đặt lại tên mười hai cung, lấy cung của tầng vận đang xét làm cung Mệnh, theo đúng thứ tự của lá số.
  • decade là null trước đại vận đầu tiên (lõi tính không có quy tắc đồng hạn, 童限) và sau đại vận thứ mười hai; day và hour là null (lõi tính không có hạn theo ngày, theo giờ).
  • Ngày được đọc theo lịch Việt Nam (UTC+7), như lá số; tháng nhuận tính như tháng mà nó lặp lại.
  • Ngoài ra có: palaceOf, starOf, flankingPalaces, palaceHas, palaceHasOneOf, palaceNotHave, withZiWeiMethods(chart) (gắn các hàm vào lá số từ localizeZiWei). Tên hàm theo kiểu iztro (astrolabe.horoscope(), palace.fliesTo()...) xem ở Chuyển từ iztro.

Bát Tự: @nhatnguyet/bat-tu

import { castBaZi, minorLuck, baZiSvg } from "@nhatnguyet/bat-tu";

const bz = castBaZi({ date: "1990-09-19", time: "20:00", gender: "male" });
bz.pillars.day.label;     // "Ding Hai"
bz.dayMaster;             // {"stem":"Ding","element":"Fire","yinYang":"Yin"}
bz.luck.startAge;         // {"years":6,"months":4}
bz.luck.pillars[0].label; // "Bing Xu"
castBaZi({ date: "1990-09-19", time: "20:00", gender: "male", terms: "han" }).pillars.day.label; // "丁亥"
bz.toSvg({ name: "An" }); // same as renderBaziSvg(bz.raw, { hoTen: "An" })

Có thể bỏ time (null): không có trụ giờ, tuổi khởi vận tính từ giữa trưa. Quy ước: giờ Việt Nam (UTC+7); năm đổi ở Lập Xuân, tháng đổi ở mỗi tiết, ngày đổi lúc 23:00 (schools: { ziHour: "split-at-midnight" } giữ trụ ngày của ngày đã nhập từ 23:00 tới 24:00, xem schools.md). Mỗi trụ có tenGod, hiddenStems, naYin, stage, selfStage, stars; minorLuck(bz, 2026) cho trụ tiểu vận của một năm ("Ding Hai").

Thần số học: @nhatnguyet/than-so-hoc

import { numerology } from "@nhatnguyet/than-so-hoc";

const n = numerology({ name: "Nguyen Van An", birthDate: "1990-09-19", today: "2026-11-19" });
// lifePath 11, expression 3, soulUrge 1, personalYear 2, karmicDebt 19
n.labels.lifePath;   // "Life Path"  ("生命灵数" with lang: "zh")
n.toSvg();           // same as renderNumerologySvg(...)

Giữ số chủ 11, 22, 33. Dấu trong tên được bỏ; chỉ chữ A-Z được tính. Ngoài ra có grid (các chữ số 1-9 của ngày sinh), pinnacles (kèm toAge), challenges.

Lễ hội: @nhatnguyet/le-hoi

import { festivals, festivalsIcs } from "@nhatnguyet/le-hoi";

festivals(2027)[2];
// {"id":"tet-nguyen-dan","date":"2027-02-06","name":"Lunar New Year (Tết)",...,"calendar":"lunar",
//  "fixedDate":"1/1","level":"major","group":"holiday","scope":"national","publicHoliday":true, ...}
festivals(2027).length;   // 164
festivalsIcs(2027);       // iCalendar (RFC 5545) text of the same list

Bộ dữ liệu có 206 lễ hội. festivals(year) trả 164 lễ có ngày âm lịch hay dương lịch cố định (cùng 164 lễ ấy cho mọi năm từ 1900 tới 2100), xếp theo ngày; 42 lễ còn lại do ban tổ chức định ngày từng năm, được kê trong DANH_SACH_LE_HOI kèm lịch đã công bố ở lich_cong_bo. Tên địa danh và tên người Việt giữ dấu trong bản tiếng Anh. group là holiday, folk-religion hay other, còn scope là national, regional, local, representative, hoặc null khi bộ dữ liệu chưa phân loại lễ ấy; mã luôn bằng tiếng Anh ở mọi lang (mã của bộ dữ liệu giữ ở raw). lang: "zh" cho 越南春节.

Mỗi lễ còn mang các trường sau, cùng bộ khoá tiếng Anh ở mọi ngôn ngữ: provinces ([{ code, name }], theo bản đồ 34 tỉnh thành năm 2025; mã kê ở PROVINCES), nationwide (boolean), ethnicGroups (tên theo danh mục chính thức 54 dân tộc, chỉ có khi phần mô tả nói rõ lễ của dân tộc nào), venues ([{ name, coordinates: { lat, lon } | null, sourceUrl: string | null }], chỉ ghi tọa độ khi có nguồn) và daysBefore, daysAfter (mùa lễ theo lệ quanh date). festivalsIcs(year, { lang }) (Python festivals_ics(year, lang=...), dòng lệnh nhatnguyet festivals 2027 --ics) ghi cùng danh sách ấy thành iCalendar: sự kiện cả ngày trải suốt mùa lễ, UID ổn định <id>-<year>@nhatnguyet.org, dòng ghi nguồn bộ dữ liệu ở X-WR-CALDESC.

Python

Cùng các hàm ấy, viết snake_case, tham số theo tên, cùng bộ khoá kết quả:

from nhatnguyet import cast_zi_wei, cast_bazi, to_lunar, numerology, festivals, decade_luck, zi_wei_svg

c = cast_zi_wei(date="1990-09-19", time="20:00", gender="male", lang="zh", view_year=2026)
c["palaces"][c["lifePalace"]]["name"]   # '命宫'
c["bureau"]                             # {'number': 5, 'name': '土五局'}
decade_luck(c)[3]["palace"]             # '田宅宫'
cast_bazi(date="1990-09-19", time="20:00", gender="male")["pillars"]["day"]["label"]   # 'Ding Hai'
cast_bazi(date="1990-09-19", time="20:00", gender="male", terms="vi")["pillars"]["day"]["label"]  # 'Đinh Hợi'
to_lunar("2027-02-06", country="KR")["month"]                                         # 12
numerology("Nguyen Van An", "1990-09-19", today="2026-11-19")["lifePath"]              # 11
festivals(2027, lang="zh")[2]["name"]                                                  # '越南春节'
svg = zi_wei_svg(c, theme="dark")

Tra cứu và vận hạn (cũng nhập được từ nhatnguyet và nhatnguyet.ziwei) nằm ở nhatnguyet.tu_vi_chuc_nang (cùng JSON với TypeScript, khớp từng byte):

from nhatnguyet import cast_zi_wei
from nhatnguyet.tu_vi_chuc_nang import horoscope, palace_of, surrounding_palaces, flying_transformations, flies_to

c = cast_zi_wei(date="1990-09-19", time="20:00", gender="male")
horoscope(c, date="2026-11-19")["year"]["palace"]            # 'Health'
surrounding_palaces(c, "Life Palace")["career"]["name"]       # 'Career'
flies_to(c, "Life Palace", "Travel", "ji")                    # False

Ngoài ra có to_solar(year, month, day, leap=False, country=...), solar_terms, solar_term_on, day_pillar, year_pillar, hour_branch, auspicious_hours, yearly_luck, yearly_stars, find_patterns, minor_luck, bazi_svg, numerology_svg, đều nhập được từ nhatnguyet. Ngày nhận cả datetime.date và bộ (year, month, day).

Các mô-đun đặt tên tiếng Anh tương ứng với các gói npm: nhatnguyet.lunar, nhatnguyet.ziwei (kèm các hàm tra cứu và horoscope), nhatnguyet.bazi, nhatnguyet.numerology và nhatnguyet.festivals, mỗi mô-đun có các hàm tiếng Anh cộng toàn bộ nội dung của mô-đun đặt tên tiếng Việt. Hai mô-đun cuối cũng gọi được như hàm, nên nhatnguyet.festivals(2027) và nhatnguyet.numerology(...) vẫn chạy dù tên ấy trỏ tới hàm hay tới mô-đun.

>>> from nhatnguyet.lunar import auspicious_hours
>>> [h["branch"] for h in auspicious_hours("2027-02-06")["hours"] if h["auspicious"]]
['Yin', 'Chen', 'Si', 'Shen', 'You', 'Hai']
>>> from nhatnguyet.festivals import festivals
>>> [f["date"] for f in festivals(2027) if f["id"] == "tet-nguyen-dan"]
['2027-02-06']

Dòng lệnh

Đây là đoạn trích: khối dưới chỉ có phần đầu của kết quả, tức lưới 12 cung và phần chú giải.

npx @nhatnguyet/cli ziwei 1990-09-19 20:00 male --name "Nguyen Van An" --year 2026
python -m nhatnguyet ziwei 1990-09-19 20:00 male --name "Nguyen Van An" --year 2026
┌────────────────────┬────────────────────┬────────────────────┬────────────────────┐
│ Travel             │ Health             │ Wealth · Body      │ Children           │
│ Xin Si             │ Ren Wu Jie Kong    │ Gui Wei Jie Kong   │ Jia Shen           │
│ Celestial Mechanism│ Purple Star Ex     │ Spinning Top,      │ Army Breaker We    │
│   Pr               │ Celestial Leader,  │ Celestial Void     │ Prosperity,        │
│ Celestial Talent,  │ Celestial Fortune, │ Nurture            │ Celestial Horse,   │
│ Bell Star,         │ Celestial Messen…  │                    │ Celestial Charm,   │
│ Shattering Star    │ Conception         │                    │ Celestial Physic…, │
│ Extinction         │                    │                    │ Solitary Star,     │
│                    │                    │                    │ Flowing Haze       │
│                    │                    │                    │ Growth             │
├────────────────────┼────────────────────┴────────────────────┼────────────────────┤
│ Friends/Subordinat…│                                         │ Spouse             │
│ Geng Chen          │                                         │ Yi You             │
│ Seven Killings We  │                                         │ Sword Ram,         │
│ Phoenix Pavilion,  │                                         │ Earthly Robber,    │
│ Celestial Punish…, │                                         │ Dipper Lord,       │
│ State Seal,        │                                         │ Red Phoenix        │
│ Releasing Spirit,  │                                         │ Bathing            │
│ Terrace Aide,      │                                         │                    │
│ Celestial Injury,  │          ZI WEI DOU SHU CHART           │                    │
│ Celestial Net,     │              Nguyen Van An              │                    │
│ Widow Star         │       Born 1990-09-19 20:00 (Xu)        │                    │
│ Tomb               │       Lunar 1990-08-01 · Geng Wu        │                    │
├────────────────────┤                Yang Male                ├────────────────────┤
│ Career             │           Bureau: Earth Five            │ Siblings           │
│ Ji Mao             │      Na yin: Earth by the Roadside      │ Bing Xu Xun Kong   │
│ Sun Pr Lu          │          Life: Hai · Body: Wei          │ Purity Ex          │
│ Celestial Beam Pr  │                                         │ Celestial Treasury │
│ Right Assistant,   │                                         │   Pr               │
│ Peach Blossom,     │                                         │ Dragon Pool,       │
│ Eight Seats,       │                                         │ Earthly Snare,     │
│ Celestial Nobili…, │                                         │ Canopy             │
│ Celestial Virtue,  │                                         │ Youth              │
│ Celestial Joy,     │                                         │                    │
│ Celestial Release  │                                         │                    │
│ Death              │                                         │                    │
├────────────────────┼────────────────────┬────────────────────┼────────────────────┤
│ Property           │ Fortune/Virtue     │ Parents            │ Life Palace        │
│ Wu Yin             │ Ji Chou            │ Wu Zi              │ Ding Hai Xun Kong  │
│ Military Song      │ Celestial Blessing │ Greedy Wolf We     │ Moon Ex Ji         │
│   Pr Quan          │   We Ke            │ Literary Glory,    │ Left Assistant,    │
│ Celestial Minister │ Giant Gate We      │ Celestial Weeping, │ Three Terraces,    │
│   Ex               │ Earthly Void,      │ Celestial Emptin…, │ Grace Light,       │
│ Celestial Halberd, │ Celestial Longev…, │ Patent of Honour   │ Celestial Offici…, │
│ Literary Melody,   │ Court Tally        │ Peak               │ Fire Star,         │
│ Earthly Release,   │ Decline            │                    │ Monthly Virtue,    │
│ Celestial Kitchen  │                    │                    │ Robbery Sha,       │
│ Illness            │                    │                    │ Annual Literary …  │
│                    │                    │                    │ Prime              │
└────────────────────┴────────────────────┴────────────────────┴────────────────────┘
Brightness: Ex exalted, Pr prosperous, Fa favorable, Ne neutral, We weak. Ages are East
Asian ages (1 at birth).

Sau lưới (phần đã cắt khỏi đoạn trích bên trên), lệnh in năm xem, mười hai đại vận, các cách cục và phần ghi chú. Các lệnh khác:

nhatnguyet bazi 1990-09-19 20:00 male --lang zh
nhatnguyet bazi 1990-09-19 female --terms han  # birth time unknown; stems and branches as 庚午
nhatnguyet lunar 2027-02-06 --country CN
nhatnguyet solar 2023-02-01 --leap             # lunar to Gregorian: 2023-03-22
nhatnguyet terms 2027 --country KR
nhatnguyet hours 2027-02-06                    # auspicious and inauspicious double hours
nhatnguyet numerology "Nguyen Van An" 1990-09-19 --today 2026-11-19
nhatnguyet festivals 2027 --lang vi
nhatnguyet ziwei 1990-09-19 20:00 male --svg chart.svg --theme dark
$ nhatnguyet lunar 2027-02-06 --country CN
┌────────────┬─────────────────┐
│ Gregorian  │ 2027-02-06      │
│ Lunar      │ 2027-01-01      │
│ Year       │ Ding Wei · Goat │
│ Month      │ Ren Yin         │
│ Day        │ Bing Chen       │
│ Solar term │ Start of Spring │
│ Calendar   │ CN (UTC+8)      │
└────────────┴─────────────────┘

$ nhatnguyet solar 2023-02-01 --leap
┌────────────┬───────────────────┐
│ Gregorian  │ 2023-03-22        │
│ Lunar      │ 2023-02 (leap)-01 │
│ Year       │ Gui Mao · Cat     │
│ Month      │ Yi Mao            │
│ Day        │ Ji Mao            │
│ Solar term │ Vernal Equinox    │
│ Calendar   │ VN (UTC+7)        │
└────────────┴───────────────────┘

$ nhatnguyet hours 2027-02-06
AUSPICIOUS HOURS  2027-02-06 · Day Bing Chen
┌───────────────┬─────────────┬──────────────┬───────────┐
│ Zi (Rat)      │ 23:00-00:59 │ inauspicious │ Tian Lao  │
│ Chou (Ox)     │ 01:00-02:59 │ inauspicious │ Yuan Wu   │
│ Yin (Tiger)   │ 03:00-04:59 │ auspicious   │ Si Ming   │
│ Mao (Cat)     │ 05:00-06:59 │ inauspicious │ Gou Chen  │
│ Chen (Dragon) │ 07:00-08:59 │ auspicious   │ Qing Long │
│ Si (Snake)    │ 09:00-10:59 │ auspicious   │ Ming Tang │
│ Wu (Horse)    │ 11:00-12:59 │ inauspicious │ Tian Xing │
│ Wei (Goat)    │ 13:00-14:59 │ inauspicious │ Zhu Que   │
│ Shen (Monkey) │ 15:00-16:59 │ auspicious   │ Jin Kui   │
│ You (Rooster) │ 17:00-18:59 │ auspicious   │ Bao Guang │
│ Xu (Dog)      │ 19:00-20:59 │ inauspicious │ Bai Hu    │
│ Hai (Pig)     │ 21:00-22:59 │ auspicious   │ Yu Tang   │
└───────────────┴─────────────┴──────────────┴───────────┘

--json in JSON (không có raw), --lang en|vi|zh chọn ngôn ngữ, --terms pinyin|han|vi chọn cách bản tiếng Anh viết can chi, --svg <file> ghi thêm lá số thành SVG (ziwei, bazi, numerology). Tên công cụ MCP cũng dùng được làm tên lệnh (cast_ziwei, cast_bazi, lunar_convert, solar_terms, auspicious_hours; cả tên cũ cast_zi_wei, zi_wei). Màu chỉ dùng khi in ra cửa sổ dòng lệnh, tắt bằng NO_COLOR hay --no-color.