taiwan-holiday-cli


台灣國定假日查詢 CLI 工具 - 快速查詢台灣假期、計算工作天數

> 🎉 現已發佈於 npm，可直接安裝使用！

Features

- 查詢指定日期是否為假期
- 支援自然語言日期輸入（today, tomorrow, next monday...）
- 查詢日期範圍內的假期
- 計算工作天數統計
- 支援多種輸出格式（simple, json, table）
- 內建快取機制，離線可用
- Shell 自動補全支援

Requirements

- Node.js >= 20.0.0

Installation

``bash


全域安裝

npm install -g taiwan-holiday-cli

或使用 npx 直接執行（無需安裝）

npx taiwan-holiday-cli today
`

驗證安裝：

`bash
holiday --version


1.0.0


`

Quick Start

`bash


查詢今天是否為假期

holiday today

查詢指定日期

holiday 2026-10-10

查詢明天

holiday tomorrow

查詢下週一

holiday "next monday"
`

Commands

$3

`bash


查詢指定日期

holiday check
holiday # 簡寫

查詢今天

holiday today

查詢接下來的假期

holiday next # 顯示下一個假期
holiday next 5 # 顯示接下來 5 個假期
holiday next 5 --skip-weekends # 跳過週末，只顯示特殊假日
`

$3

`bash


查詢日期範圍內的假期

holiday range
holiday range 2026-01-01 2026-01-31

查詢指定月份

holiday month [year-month]
holiday month 2026-10
`

$3

`bash


年度假期統計

holiday stats
holiday stats 2026

月份假期統計

holiday stats
holiday stats 2026 10

計算工作天數

holiday workdays
holiday workdays 2026-01

計算兩日期間的天數

holiday between
holiday between 2026-01-01 2026-01-31
`

$3

`bash


列出指定年份所有假期

holiday list

顯示支援的年份範圍

holiday years

快取管理

holiday cache status # 查看快取狀態
holiday cache clear # 清除快取

設定管理

holiday config list # 列出設定
holiday config get # 取得設定值
holiday config set # 設定值

系統健康檢查

holiday health

Shell 自動補全

holiday completion bash # Bash
holiday completion zsh # Zsh
holiday completion fish # Fish
`

Output Formats

所有查詢命令都支援 -f, --format 選項：

`bash


Simple 格式（預設）

holiday today

2026-01-04 (日) 是假期：週末

JSON 格式

holiday today -f json

{

"date": "2026-01-04",

"week": "日",

"isHoliday": true,

"description": ""

}

Table 格式

holiday today -f table

┌────────────┬──────┬──────────┬──────┐

│ 日期 │ 星期 │ 是否假期 │ 說明 │

├────────────┼──────┼──────────┼──────┤

│ 2026-01-04 │ 日 │ ✓ │ 週末 │

└────────────┴──────┴──────────┴──────┘

`

設定預設格式：

`bash
holiday config set format json
`

Date Formats

支援多種日期格式：

| 格式 | 範例 |
|------|------|
| ISO | 2026-01-01 |
| 斜線 | 2026/01/01 |
| 無分隔 | 20260101 |
| 相對日期 | today, tomorrow, yesterday |
| 自然語言 | next monday, next friday |

Supported Years

目前支援 2017-2026 年的台灣假期資料。

`bash
holiday years


支援的年份範圍：2017-2026 (共 10 年)


`

Global Options

`bash
--no-cache # 強制從 API 重新獲取，不使用快取
--help # 顯示說明
--version # 顯示版本
`

Shell Completion

$3

`bash
holiday completion bash >> ~/.bashrc
source ~/.bashrc
`

$3

`bash
holiday completion zsh >> ~/.zshrc
source ~/.zshrc
`

$3

`bash
holiday completion fish > ~/.config/fish/completions/holiday.fish
`

Data Source

假期資料來自 TaiwanCalendar 專案，感謝 @ruyut 的維護。

Development

`bash


Clone

git clone https://github.com/lis186/taiwan-holiday-cli.git
cd taiwan-holiday-cli

Install dependencies

npm install

Development

npm run dev -- today

Build

npm run build

Test

npm test

Test with coverage

npm run test:coverage
``

License

MIT License - see LICENSE for details.

Contributing

歡迎貢獻！請參閱 CONTRIBUTING.md。