GTFS 工具 CLI

导入 GTFS 数据源、查询公交数据、浏览线路/班次/日历/形状、比较班次时刻表、编辑站点/通道/线路/班次/停靠时间、导出更改或打开本地仪表板。

参考文件

当您需要确切的列名、SQL 语法或标志详细信息时，请阅读以下文件：

references/commands.md — 所有 CLI 命令，包含标志和示例
references/edits.md — 应用班次/时刻表/服务编辑以及用于向 CLI 提供服务更改的 changeset 格式
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

使用 anthropic、openai、google 或 generic 作为 AI 提供商。运行 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 存档，并在导入后删除。下载和验证失败（不是 zip 文件，没有 stops.txt）时，当前数据集保持不变；但 DuckDB 导入过程中的失败仍会清除当前数据集，这与本地文件的行为相同。查询字符串（预签名 URL）用于下载，但从不存储或打印。包含嵌入用户名或密码的 URL 将被拒绝，其他方案（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 环境变量、通过临时 credential_chain 密钥的 AWS 配置文件或 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"      # 无障碍
gtfs-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                              # 构建并行路线线条带 (Separate Route(s))
gtfs-tools route-bands --data                       # 打印 band_rows、routes、widest_bundle
gtfs-tools route-bands --status --data              # 报告现有条带计数而不重新构建

仅从 GTFS shapes 构建 RouteShapeBandsTable：共享走廊的路线会汇聚到一条中心线上，并分配横向车道，以便仪表板的 Separate Route(s) 视图将它们绘制为平行条带。使用此命令而非 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

位置类型：Station（站点）、Stop（停靠点）、Exit/Entrance（出口/入口）、Generic Node（通用节点）、Boarding Area（登车区）。

首先查找停靠点 ID：

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

编辑班次、时刻表与服务

将服务更改（例如来自警报页面）应用到已导入的数据源。CLI 不直接读取警报——您需要将更改转换为编辑。请参阅 references/edits.md 了解完整的 changeset 格式、读取→检查→确认→实施→审查的工作流程，以及警报验证报告格式（数据内状态 + 警报描述 + 源链接 + 可点击的、CLI 验证的仪表板链接）。它还涵盖了将班次改道至另一条线路（例如 "A/C 经由 F 运行"）的操作，使用 gtfs-tools reroute——该命令会将捐赠线路的停靠点拼接进来并调整时间，而不仅仅是跳过停靠点——以及使用 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                             # 级联删除停靠时间

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 export /path/to/output.zip              # 导出完整数据源
gtfs-tools export /path/to/output.zip --tables stops,pathways  # 仅导出特定表
gtfs-tools export /path/to/output --directory       # 导出为目录结构
gtfs-tools export --url-only                       # 打印导出链接而不下载

SQL 查询

针对导入的数据集运行原始 SQL：

gtfs-tools query --sql "SELECT stop_name, stop_lat, stop_lon FROM StopsTable WHERE stop_name LIKE '%Park%'"
gtfs-tools query --sql "SELECT trip_id, count(*) as stops FROM StopTimesTable GROUP BY trip_id" --data

命名查询提供快捷方式：

gtfs-tools query --stations --args "Park"
gtfs-tools query --pathways-connected-to node-pktrm-stair7-gl
gtfs-tools query --name station-stops --args-json '{"stationId":"place-pktrm"}'
gtfs-tools queries                                 # 列出所有命名查询

使用 --data 在终端中打印结果，或省略它以在仪表板中打开。

故障排除

“找不到命令”：确保 npm install -g @gabrielahn/gtfs-tools 成功完成，并且您的 PATH 包含 npm 全局 bin 目录（npm bin -g 会显示它）。
“导入失败”：验证数据源文件是有效的 zip 存档，并且包含 stops.txt。远程 URL 必须公开可访问或通过 S3/R2 密钥进行身份验证。
“仪表板未打开”：在 http://localhost:3xxx 检查浏览器。如果端口已被占用，CLI 会自动尝试下一个端口。
“技能文件未找到”：运行 gtfs-tools install-skill <provider> 或 npx skills add gabrielAHN/gtfs-tools。对于自定义目录，使用 --target-dir。
“数据集过期”：数据在 7 天后自动过期。重新导入数据源以刷新。
“权限错误”：如果遇到 EACCES 错误，请参阅 npm 关于修复权限的文档，或使用 nvm/node 版本管理器。

gabrielAHN/gtfs-tools

gtfs-tools 是什么？

在你喜欢的 AI 中提问

文档

GTFS 工具 CLI

参考文件

安装

快速开始

导入

浏览与筛选

仪表板

站点查询

通道与连接

线路与服务

班次与停靠时间

日历与形状

路线线条带

站点线路与寻路

数据编辑（连接）

数据编辑（节点）

编辑班次、时刻表与服务

导出

SQL 查询

故障排除

相关技能

steipete/gemini

steipete/gh-issues

steipete/skill-creator

steipete/clawhub

steipete/coding-agent

steipete/mcporter