x-cmd Overview
ccal is a Chinese calendar module that provides:
- Gregorian and lunar calendar conversion
- Solar terms (节气)
- Traditional Chinese holidays
- Almanac guidance (黄历宜忌)
- Heavenly Stems and Earthly Branches (干支)
- Six-day cycle (六曜)
- Duty star (值星)
AI Agent Usage
Output Modes
| Mode | Command | Use Case |
|---|---|---|
| YML (default in pipe) | x ccal info <date> |
AI parsing, structured key-value output |
| TSV | x ccal info --tsv <date> |
Piping to other tools, tab-separated |
| CSV | x ccal info --csv <date> |
Spreadsheet import |
| TTY (default in terminal) | x ccal info --tty <date> |
Human viewing, colorful calendar draw |
Auto-Detection
When output is not a TTY (piped to another process):
- Automatically outputs YML format
- Same as calling
x ccal info --yml <date>
When output is a TTY (interactive terminal):
- Uses
x ccal drawto render colorful calendar - Same as calling
x ccal info --tty <date>
Basic Examples
# AI: Get today's date info (auto-detects pipe vs terminal)
x ccal info
# AI: Get specific date in YML format
x ccal info --yml 2025-05-09
# AI: Parse YML output with your favorite tool
x ccal info --yml 2025-05-09 | grep "jianchu"
# TSV format (tab-separated)
x ccal info --tsv 2025-05-09
# CSV format (comma-separated)
x ccal info --csv 2025-05-09
# Force TTY mode even in pipe
x ccal info --tty 2025-05-09
YML Output Format
date: 2025-05-09
lunar_date: 2025-4-12
lunar_daycount: 29
jianchu: 收
weekday: 五
bazi: 乙巳 辛巳 戊寅
jieqi: 无
jieqi_next: 小满 (5, 21)
holiday: 无
xiuxi: 无
related: 无
yi: 结网 解除 馀事勿取
ji: 诸事不宜
YML Field Descriptions
| Field | Description | Example |
|---|---|---|
| date | Gregorian date (YYYY-MM-DD) | 2025-05-09 |
| lunar_date | Lunar date (YYYY-M-D) | 2025-4-12 |
| lunar_daycount | Days in lunar month (29/30) | 29 |
| jianchu | 值星 (auspicious/inauspicious star) | 收/满/定/执... |
| weekday | Day of week (一-日) | 五 |
| bazi | Year/Month/Day Heavenly Stems | 乙巳 辛巳 戊寅 |
| jieqi | Solar term | 立夏/清明/无 |
| jieqi_next | Next solar term with date | 小满 (5, 21) |
| holiday | Holiday name | 劳动节/无 |
| xiuxi | 休(holiday)/工(workday)/空 | 休 |
| related | Holiday adjustment info | 劳动节 2025-05-01 |
| yi | 宜 (auspicious activities) | 出行 嫁娶 安葬... |
| ji | 忌 (inauspicious activities) | 动土 破土 祈福... |
Key Fields for AI
值星 (jianchu) - Duty star for the day:
- 吉: 满/平/定/执 (auspicious)
- 凶: 收/破 (inauspicious)
宜 (yi) - Auspicious activities for the day 忌 (ji) - Inauspicious activities for the day
六曜 (liuyao) - Six-day cycle:
- 大安 ( auspicious)
- 赤口 (inauspicious)
- 先胜/友引/先负/佛灭
Data Format (TSV)
The raw TSV data has 13 columns:
date lunar_date daycount jianchu wd bazi jieqi jieqi_next holiday xiuxi related yi ji
2025-05-09 2025-4-12 29 收 五 乙巳 辛巳 戊寅 无 小满 (5, 21) 无 无 无 结网 解除 馀事勿取 诸事不宜
Data Source
Archive Location
$___X_CMD_ROOT_DATA/ccal/data/
├── ccal-data-v0.0.6.tar.xz # Main archive (stream-read, not extracted)
└── v0.0.6/cache/ # Pre-extracted index (after first run)
├── year.tsv # Year index
└── month.tsv # Month index
Download
- URL: https://codeberg.org/x-cmd/ccal-data/releases/download/v0.0.6/ccal-data.tar.xz
- Trigger: First run or
x ccal lunar update
Archive Contents
ccal-data/
├── index/
│ ├── year.tsv # Year index
│ └── month.tsv # Month index
└── lunar/
└── {year}_{month}.tsv # Monthly data (e.g., 2026_03.tsv)
Direct Read (No Extraction)
DATA="$___X_CMD_ROOT_DATA/ccal/data/ccal-data-v0.0.6.tar.xz"
# Read specific month: 2026 March
x zuz cat "$DATA" ccal-data/lunar/2026_03.tsv
# Read all months of 2026
x zuz cat "$DATA" ccal-data/lunar/2026_*.tsv
Reference
lib/awk/lunar.awk- Lunar calendar computationlib/awk/gongli.awk- Gregorian calendar computationlib/awk/ccal.awk- Main calendar logic