GTFS 工具命令列介面

GTFS 工具 CLI

匯入 GTFS 資料、查詢交通資料、瀏覽路線/行程/日曆/形狀、比較行程時刻表、編輯車站/通道/路線/行程/停靠時間、匯出變更，或開啟本地儀表板。

參考檔案

當你需要確切的欄位名稱、SQL 語法或旗標詳細資訊時，請閱讀以下檔案：

• references/commands.md — 所有 CLI 命令，包含旗標與範例
• references/edits.md — 套用行程/時刻表/服務編輯，以及用於將服務變更提供給 CLI 的變更集格式
• references/tables.md — 表格與檢視表的綱要，包含欄位型別
• gtfs 擴充函式參考 — 每個 SQL 函式都附有可執行的範例 (markdown)
• GTFS 工具 CLI 文件 與文件索引 — 每個文件頁面都以 markdown 格式呈現
• references/gtfs-schedule-reference.md — GTFS 時刻表欄位參考，專注於車站零件、通道與遺漏連線稽核
• references/examples.sql — 實用的 SQL 查詢範例

安裝

全域安裝 CLI 並註冊技能：

npm install -g @gabrielahn/gtfs-tools
gtfs-tools install-skill openai

或者透過 npx 僅安裝技能：

npx skills add gabrielAHN/gtfs-tools

對於 AI 提供者，請使用 anthropic、openai、google 或 generic。執行 gtfs-tools install-skill --list-providers 來查看解析後的安裝路徑。--provider <name> 等同於位置參數的提供者名稱，而 --target-dir <dir> 會覆蓋預設值。即使是非互動式使用，當設定 --target-dir 時仍需要一個提供者。如果旁邊存在舊版的 gtfs-viz 技能目錄，它會被保留並回報為過時；請在安裝此技能後自行將其移除。

使用 gtfs-tools h 取得一般說明，或使用 gtfs-tools h <command> 取得與 gtfs-tools help <command> 和 gtfs-tools <command> -h 相同的命令特定說明。

顯示或更新已安裝的 CLI：

gtfs-tools --version
gtfs-tools update --check
gtfs-tools update
gtfs-tools update --provider openai

update 會保留已匯入的資料集與工作階段。在 CLI 更新後，加上 --provider 可重新整理該提供者已安裝的技能。

從 gabrielAHN/gtfs-tools 的簽出版本：

npm ci
npm run build
npm install -g .

快速入門

gtfs-tools import /path/to/feed.zip
gtfs-tools status
gtfs-tools stations
gtfs-tools station "Park Street"
gtfs-tools station_pathways "Park Street" --data

匯入

gtfs-tools import /absolute/path/to/feed.zip
gtfs-tools import https://example.com/gtfs/feed.zip
gtfs-tools import s3://my-bucket/gtfs/feed.zip      # 也支援 s3a://, s3n://
gtfs-tools import r2://my-bucket/gtfs/feed.zip

使用一般或引號括起來的路徑或 URL。請勿使用反引號。匯入是一次性的；新的匯入會取代目前的資料集。資料儲存在 ~/.gtfs-viz-cli/current。資料集會在 7 天後自動過期。

遠端資料會先下載到 ~/.gtfs-viz-cli/downloads/，必須是壓縮封存檔，並在匯入後刪除。下載和驗證失敗 (不是 zip、缺少 stops.txt) 時，目前的資料集保持不變；如果 DuckDB 匯入本身失敗 (與本機檔案相同)，則仍然會清除目前資料集。查詢字串 (預先簽署的 URL) 用於下載，但絕不會儲存或列印。包含內嵌使用者名稱或密碼的 URL 會被拒絕，其他 scheme (gs://、az://、hf:// 等) 則不受支援。http(s) URL 路徑中未編碼的 @ 也會被拒絕：請將其百分比編碼為 %40，並且絕對不要將憑證放在 URL 中。

s3:// 和 r2:// 物件透過 DuckDB 秘密金鑰進行身分驗證：首先嘗試任何符合的秘密金鑰 (包括持續性的，例如 duckdb -c "CREATE PERSISTENT SECRET (TYPE s3, KEY_ID '…', SECRET '…', REGION 'us-east-1')")；然後，對於 s3://，嘗試 AWS 環境變數、AWS 設定檔或透過暫時 credential_chain 秘密的 SSO；最後是匿名請求。r2:// 需要 CREATE PERSISTENT SECRET (TYPE r2, KEY_ID '…', SECRET '…', ACCOUNT_ID '…')。MinIO 和其他 S3 相容儲存使用帶有 ENDPOINT、URL_STYLE 'path' 和 USE_SSL 的 s3 秘密。絕不要要求使用者將秘密值貼到你要執行的命令中；請要求他們自行建立秘密。

瀏覽與篩選

直接在 CLI 中篩選車站或站點：

gtfs-tools stations                                # 所有車站
gtfs-tools stations --name "Park"                  # 名稱包含 "Park"
gtfs-tools stations --pathways "no"                # 沒有通道
gtfs-tools stations --wheelchair "accessible"      # 無障礙
ngtfs-tools stations --station-id place-pktrm       # 精確 ID
gtfs-tools stations --name "Park" --pathways "yes" # 組合

gtfs-tools stops                                   # 所有獨立站點
gtfs-tools stops --name "Albany"                    # 名稱包含 "Albany"
gtfs-tools stops --location-type "Stop"             # 依類型
gtfs-tools stops --wheelchair "unknown"             # 依無障礙狀態

gtfs-tools trips                                   # 開啟行程檢視
gtfs-tools trips --route R1 --data                 # 特定路線的行程
gtfs-tools trip trip-123 --data                    # 特定行程的停靠時間
gtfs-tools trip trip-123 --view timeline           # 開啟時間軸檢視
gtfs-tools trip trip-123 --compare trip-456        # 比較兩個行程

gtfs-tools calendar --data                         # 列出所有服務
gtfs-tools calendar SAT-1 --data                   # 特定服務的日曆

gtfs-tools shapes --data                           # 列出所有形狀
gtfs-tools shapes shape-123 --data                 # 特定形狀的點

加上 --format json 以輸出 JSON 格式。

儀表板

命令預設會開啟儀表板。加上 --data 可以改為列印資料列。

gtfs-tools station "Park Street"                    # 開啟車站資訊
gtfs-tools station "Park Street" --data             # 列印資料列
gtfs-tools stop-info "Trade Center"                 # 開啟帶有彈出視窗 + 縮放的地圖
gtfs-tools station_connections "Park Street"         # 開啟流程圖
gtfs-tools station_pathways place-pktrm --node-id node-pktrm-stair7-gl
gtfs-tools view --view stations/map --map-focus 42.355,-71.06,12
gtfs-tools view --view export --url-only

將列印出的儀表板 URL 回傳給使用者。

車站查詢

gtfs-tools station "Park Street"
gtfs-tools station --id place-pktrm --data
gtfs-tools station --id place-pktrm --format json

當值型別已知時，使用 --station-id 或 --station-name。當值可能是 ID 或名稱時，使用 --selected-station 或位置參數。

通道與連線

gtfs-tools station_connections "Park Street" --data
gtfs-tools station_pathways "Park Street" --data
gtfs-tools station_pathways place-pktrm --node-id node-pktrm-stair7-gl --data

--node-id 目標是車站內的月台、出口/入口或通道節點。

在檢查遺失的車站零件或中斷的內部連通性時，僅使用車站零件和網路功能。從 get_station_stops(station_id) 開始，然後檢查 get_station_pathways(station_id)、get_station_routes(station_id)、find_shortest_path 或 find_reachable_stops。不要從 StopsTable 稽核車站內部連通性，因為該表格用於獨立站點。請參閱 references/gtfs-schedule-reference.md。

路線與服務

gtfs-tools routes                                   # 列出所有路線
gtfs-tools routes --type Bus                        # 依類型篩選
gtfs-tools routes --route-name "Metro"              # 依名稱篩選
gtfs-tools routes --route-id ROUTE_ID               # 依 ID 篩選
gtfs-tools route "Line 1"                           # 開啟路線資訊
gtfs-tools route --route-id ROUTE_ID --data         # 列印路線資料
gtfs-tools route "Line 1" --view service            # 開啟服務檢視

行程與停靠時間

gtfs-tools trips --data                             # 列出所有行程
gtfs-tools trips --route R1 --data                  # 特定路線的行程
gtfs-tools trip trip-123 --data                     # 包含站點名稱的停靠時間
gtfs-tools trip trip-123 --data --view info          # 行程後設資料
gtfs-tools trip trip-123 --view timeline             # 開啟時間軸檢視
gtfs-tools trip trip-123 --view map                  # 開啟地圖檢視
gtfs-tools trip trip-123 --compare trip-456 --data   # 比較停靠時間
gtfs-tools trip trip-123 --compare trip-456,trip-789 --view map # 在地圖上比較 3 個行程
gtfs-tools trips --compare trip-1,trip-2,trip-3      # 在儀表板中比較行程

檢視選項：timetable (預設)、timeline (時間圖表)、map (位置)、info (搭配 --data 的後設資料)。

日曆與形狀

gtfs-tools calendar --data                          # 列出帶有行程數量的服務
gtfs-tools calendar --route R1 --data               # 特定路線的服務
gtfs-tools calendar SAT-1 --data                    # 特定服務的日曆 + 日期
gtfs-tools shapes --data                            # 列出帶有點數量的形狀
gtfs-tools shapes --route R1 --data                 # 特定路線的形狀
gtfs-tools shapes shape-123 --data                  # 特定形狀的點

路線線帶

gtfs-tools route-bands                              # 構建平行路線線帶 (分隔路線)
gtfs-tools route-bands --data                       # 列印 band_rows、routes、widest_bundle
gtfs-tools route-bands --status --data              # 報告現有頻帶數量而不重新構建

從 GTFS shapes 單獨構建 RouteShapeBandsTable：共用走廊的路線會收斂到一條中心線上，並賦予橫向車道，以便儀表板的「分隔路線」檢視將它們繪製為平行頻帶。請使用此命令而非 query 來執行走廊巨集 — 它們需要一個可寫入的空間工作階段。

車站路線與路徑查找

gtfs-tools station_routes "South Station" --data
gtfs-tools station_routes "South Station" --data --time-interval 60
gtfs-tools station_routes "South Station" --data --connection-type "Exit/Entrance"
gtfs-tools station_routes "South Station" --data --node-id door-sstat-dewey
gtfs-tools station_shortest_route "South Station" --data

station_shortest_route 根據時間找到最快的入口到出口路線。

資料編輯 (連線)

gtfs-tools add_connection --from NODE_A --to NODE_B --traversal-time 45
gtfs-tools add_connection --from NODE_A --to NODE_B --bidirectional --pathway-mode 2 --stair-count 12
gtfs-tools update_connection --pathway-id PATHWAY_ID --traversal-time 60
gtfs-tools delete_connection --pathway-id PATHWAY_ID

通道模式：1=走道、2=樓梯、3=自動步道、4=電扶梯、5=電梯、6=付費閘門、7=出口閘門。

首先尋找通道 ID：

gtfs-tools station_pathways "Park Street" --data
gtfs-tools query --sql "SELECT pathway_id, from_stop_id, to_stop_id, traversal_time FROM PathwaysView WHERE from_stop_id LIKE '%pktrm%'"

資料編輯 (節點)

gtfs-tools add_node --stop-id NEW_ID --lat 42.35 --lon -71.06 --parent-station place-pktrm
gtfs-tools add_node --stop-id door-new --stop-name "New Entrance" --lat 42.35 --lon -71.06 --location-type "Exit/Entrance" --parent-station place-pktrm
gtfs-tools update_node --stop-id NODE_ID --stop-name "Main Lobby"
gtfs-tools delete_node --stop-id NODE_ID

位置類型：車站、站點、出口/入口、通用節點、登車區。

首先尋找站點 ID：

gtfs-tools query --name station-stops --args-json '{"stationId":"place-pktrm"}' --data

編輯行程、時刻表與服務

將服務變更 (例如來自 alerts 頁面) 套用到已匯入的資料。CLI 不會讀取 alerts — 你需將變更轉換為編輯。請參閱 references/edits.md 以了解完整的變更集格式、讀取 → 檢查 → 確認 → 實施 → 審查的工作流程，以及警報驗證報告格式 (資料內狀態 + 警報描述 + 來源連結 + 可點擊、經 CLI 驗證的儀表板連結)。它還涵蓋了使用 gtfs-tools reroute 將行程重新路線規劃到另一條線路 (例如「A/C 經由 F 線運行」)— 這會插入捐贈路線的站點並調整時間，而不僅僅是跳過站點 — 並使用 gtfs-tools trip <id> --compare <donor_trip> --view map 來檢視它。

gtfs-tools add_trip --trip-id T2 --route-id R1 --service-id WKD --headsign "Uptown Express" --direction-id 0
gtfs-tools update_trip --trip-id T2 --headsign "Express"        # 僅變更給定的欄位
gtfs-tools delete_trip --trip-id T2                             # 級聯刪除至 stop_times

gtfs-tools set_stop_times --trip-id T2 --stops-json '[{"stop_sequence":1,"stop_id":"S1","arrival_time":"09:00:00","departure_time":"09:00:00"}]'
gtfs-tools reroute --trip A_TRIP   # 直接在重新路線規劃表單中開啟受影響的行程
gtfs-tools reroute --trip A_TRIP --via F_TRIP --from "W 4 St-Wash Sq" --to "Jay St-MetroTech"   # 讓 A 在這些站點之間經由 F 運行
gtfs-tools remove_stops --trip T2 --stops "Spring St,Canal St"                # 跳站/直達、車站繞行
gtfs-tools truncate_trip --trip T2 --to "14 St"                                # 提早結束 / 截短
gtfs-tools split_trip --trip T2 --gap-from "Crescent St" --gap-to "Broadway Junction" --new-trip-id T2_SEC2  # 兩段式拆分

gtfs-tools add_calendar --service-id WKND --days sat,sun --start-date 20260101 --end-date 20261231
gtfs-tools update_calendar --service-id WKD --days mon,tue,wed,thu,fri,sat
gtfs-tools delete_calendar --service-id WKND

gtfs-tools add_calendar_date --service-id WKD --date 20260906 --exception-type 1   # 1=新增服務，2=在該日期移除服務
gtfs-tools delete_calendar_date --service-id WKD --date 20260906
gtfs-tools query --write "DELETE FROM calendar_dates WHERE service_id = 'WKD' AND date = '2026-09-06'"

日曆命令是 gtfs-tools 命令，而不是 SQL。使用 query --write 直接寫入表格作為例外。刪除日曆日期時，優先使用 delete_calendar_date 而非 SQL，因為它可以正確處理無效的範疇和日期格式。

匯出

將所有資料匯出為 GTFS CSV：

gtfs-tools export /path/to/output/directory/

建立 agency.txt、stops.txt、routes.txt、trips.txt、stop_times.txt、calendar.txt、calendar_dates.txt、shapes.txt、pathways.txt、levels.txt、translations.txt、attributions.txt 以及 feed_info.txt。輸出目錄必須存在或可建立。不支援篩選；匯出會寫入整個資料集。

匯出後會列印檔案路徑、資料列計數和總大小。

搭配 Mermaid 的查詢、視覺化與結構

直接執行 SQL 查詢：

gtfs-tools query --sql "SELECT * FROM StopsView LIMIT 5"
gtfs-tools query --name station-stops --args-json '{"stationId":"place-pktrm"}'
gtfs-tools query --name station-stops --args-json '{"stationId":"place-pktrm"}' --data
gtfs-tools query --name station-stops --args-json '{"stationId":"place-pktrm"}' --format json --data

使用 --name 執行來自 ~/.gtfs-viz-cli/current/packages/queries/*.sql 具名查詢。

產生視覺化效果 (需要 DuckDB 空間擴充功能)：

gtfs-tools visualize "SELECT stop_name, stop_lat, stop_lon FROM StopsView WHERE location_type = 1"
gtfs-tools visualize --sql "SELECT stop_name, stop_lat, stop_lon FROM StopsView WHERE location_type = 1" --timeout 3000

使用 --timeout 來設定每個點的渲染逾時 (毫秒)。使用 --prefix 來設定桶字首，或使用 --output 設定輸出目錄。使用 --dry-run 來列印內部產生的圖表定義而不渲染。產生 Mermaid 或 PlantUML 圖表：

gtfs-tools mermaid "SELECT pathway_id, from_stop_id, to_stop_id, traversal_time FROM PathwaysView LIMIT 10" --data

返回 Mermaid 流程圖程式碼。PlantUML 依賴於 jar 路徑或 plantuml 命令。

產生結構描述 (請使用此命令而非直接讀取 references/tables.md)：

gtfs-tools schema --tables PathwaysView,StationsView

列出所有可用的表格與檢視表：

gtfs-tools schema --list
gtfs-tools schema --list --markdown > /path/to/write/schema.md

將結構描述儲存到檔案或傳遞給使用者。優先使用 schema --tables 而非 schema。

工作階段管理

gtfs-tools status
gtfs-tools info
gtfs-tools reset
gtfs-tools uninstall-skill
gtfs-tools install-skill openai

無障礙稽核

使用車站零件和網路功能來檢查遺失的通道或中斷的內部連通性。從 get_station_stops(station_id) 開始，然後檢查 get_station_pathways(station_id)、get_station_routes(station_id)、find_shortest_path 或 find_reachable_stops。請參閱 references/gtfs-schedule-reference.md。station_pathways 和 station_connections 檢視表會顯示車站內的連線。station_routes 會顯示進出車站的路線。station_shortest_route 會找到最快的入口到出口路線。

不要從 StopsTable 稽核車站內部連通性。使用車站零件和網路功能。不要使用名為「查詢車站」之類的查詢；查找車站 ID 的正確查詢是 station-stops。在診斷車站缺失部分時，不要使用通用指南或發明自己的方法：保留在此文件中定義的車站零件、網路和查找功能。

用於無障礙稽核的 SQL 範例：

-- 具有多個層級且沒有無障礙通道 (電梯) 的車站
SELECT
  s.stop_id AS station_id,
  s.stop_name AS station_name,
  COUNT(DISTINCT l.level_id) AS level_count
FROM StationsView s
JOIN StopLevelsView l ON s.stop_id = l.stop_id
WHERE s.stop_id NOT IN (
  SELECT DISTINCT parent_station
  FROM PathwaysView p
  JOIN stops s2 ON p.from_stop_id = s2.stop_id
  WHERE s2.location_type = 5  -- 電梯
)
GROUP BY s.stop_id, s.stop_name
HAVING COUNT(DISTINCT l.level_id) > 1
ORDER BY level_count DESC;

工作階段隔離

每個 AI 提供者都有自己的資料集。切換提供者會載入該提供者對應的資料集。

系統設定

設定檔位於 ~/.gtfs-viz-cli/config.json。重置會清除目前資料集但保留設定檔。