GTFS Tools CLI
GTFS 피드를 가져오고, 대중교통 데이터를 조회하며, 경로/운행/달력/셰이프를 탐색하고, 운행 일정을 비교하며, 정거장/경로/운행/정차 시간을 편집하고, 변경 사항을 내보내거나 로컬 대시보드를 여세요.
참조 파일
정확한 열 이름, SQL 구문 또는 플래그 세부 정보가 필요할 때 다음 파일을 참조하세요:
- references/commands.md — 모든 CLI 명령어와 플래그 및 예제
- references/edits.md — 운행/일정/서비스 편집 적용 및 CLI에 서비스 변경 사항을 전달하기 위한 변경 세트 형식
- references/tables.md — 열 유형이 포함된 테이블 및 뷰 스키마
gtfs확장 함수 참조 — 모든 SQL 함수와 실행 가능한 예제 (markdown)- GTFS Tools CLI 문서 및 문서 인덱스 — 모든 문서 페이지 (markdown)
- references/gtfs-schedule-reference.md — 정거장 부품, 경로 및 누락 연결 감사에 초점을 맞춘 GTFS Schedule 필드 참조
- 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 아카이브여야 하고 가져오기 후 삭제됩니다. 다운로드 및 유효성 검사 실패(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 # 셰이프의 포인트
JSON 출력을 위해 --format 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을 사용하세요. 둘 다 가능할 때는 --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는 알림을 읽지 않습니다. 변경 사항을 편집으로 변환합니다. 전체 변경 세트 형식, 읽기 → 확인 → 확인 → 구현 → 검토 워크플로, 그리고 알림-유효성 검사 보고서 형식(데이터 내 상태 + 알림 설명 + 소스 링크 + 클릭 가능한 CLI 검증 대시보드 링크)은 references/edits.md를 참조하세요. 또한 다른 노선으로 운행 경로 변경(예: "A/C via the 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 # 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" # 해당 정류장 사이에서 F를 통해 A 운행
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 add_service --service-id NEW_SVC --days mon,tue,wed,thu,fri,sat,sun --start-date 20260101 --end-date 20261231
gtfs-tools update_service --service-id NEW_SVC --days mon,tue,wed,thu,fri --start-date 20260101 --end-date 20261231
gtfs-tools delete_service --service-id NEW_SVC
gtfs-tools add_fare_attribute --fare-id FA --price 2.50 --currency USD --payment-method 0 --transfers 0
gtfs-tools update_fare_attribute --fare-id FA --price 2.75
gtfs-tools delete_fare_attribute --fare-id FA
gtfs-tools add_fare_rule --fare-id FA --route-id R1 --origin-id Z1 --destination-id Z2
gtfs-tools delete_fare_rule --fare-id FA --route-id R1 --origin-id Z1 --destination-id Z2
gtfs-tools add_fare_media --fare-media-id OMNY --fare-media-name "OMNY" --fare-media-type 2
gtfs-tools update_fare_media --fare-media-id OMNY --fare-media-name "OMNY Card"
gtfs-tools delete_fare_media --fare-media-id OMNY
gtfs-tools add_rider_category --rider-category-id SR --rider-category-name "Senior" --min-age 65
gtfs-tools update_rider_category --rider-category-id SR --rider-category-name "Senior/Disabled" --min-age 65 --max-age null
gtfs-tools delete_rider_category --rider-category-id SR
gtfs-tools add_fare_leg_rule --fare-leg-rule-id FLR --network-id N1 --from-area-id A1 --to-area-id A2 --min-price 2.50 --max-price 5.00
gtfs-tools update_fare_leg_rule --fare-leg-rule-id FLR --min-price 2.75
gtfs-tools delete_fare_leg_rule --fare-leg-rule-id FLR
gtfs-tools add_fare_transfer_rule --fare-transfer-rule-id FTR --from-fare-product-id FP1 --to-fare-product-id FP2 --transfer-count 2 --duration-limit 7200
gtfs-tools update_fare_transfer_rule --fare-transfer-rule-id FTR --duration-limit 5400
gtfs-tools delete_fare_transfer_rule --fare-transfer-rule-id FTR
gtfs-tools add_area --area-id A1 --area-name "Downtown"
gtfs-tools update_area --area-id A1 --area-name "City Center"
gtfs-tools delete_area --area-id A1
gtfs-tools add_stop_area --area-id A1 --stop-id S1
gtfs-tools delete_stop_area --area-id A1 --stop-id S1
내보내기
gtfs-tools export /path/to/output.zip
gtfs-tools export /path/to/output/ --format csv
gtfs-tools export --diff /path/to/output.diff.zip
내보내기는 전체 GTFS 피드를 zip 또는 디렉토리로 내보냅니다. --diff는 변경된 행만 내보내고 원래 값과 새 값을 모두 포함합니다. 차이점은 대시보드의 'Export' 뷰에서도 다운로드할 수 있습니다.
대시보드 뷰
gtfs-tools view # 선택기로 대시보드 열기
gtfs-tools view --view export # 내보내기 뷰 열기
gtfs-tools view --view stations/map --map-focus 42.355,-71.06,12
gtfs-tools view --view stations/map --map-focus 42.355,-71.06,12 --zoom 15
gtfs-tools view --view stations/map --map-focus 42.338,-71.015,12,16
--view 선택 사항: export, stations/map, stations/table, routes, trips, calendar, shapes, alerts, status. --map-focus는 위도, 경도, 줌(선택 사항) 및 베어링(선택 사항)입니다.
감사
gtfs-tools audit # 모든 감사 실행
gtfs-tools audit --report # 감사 보고서 생성
gtfs-tools audit --category pathways # 경로 감사로 범위 지정
gtfs-tools audit --category accessibility # 접근성 감사
gtfs-tools audit --category connectivity # 연결 감사
gtfs-tools audit --category schedule # 일정 감사
gtfs-tools audit --category fare # 요금 감사
--report는 감사 보고서를 생성합니다. --category는 감사를 특정 범주로 필터링합니다.
쿼리
gtfs-tools query --name station-stops --args-json '{"stationId":"place-pktrm"}' --data
gtfs-tools query --sql "SELECT * FROM StopsView WHERE parent_station = 'place-pktrm'" --data
gtfs-tools query --sql "SELECT count(*) FROM TripsView" --data
gtfs-tools query --sql "SELECT * FROM RoutesView WHERE route_type = 3" --data --format json
--name은 queries 디렉토리의 이름이 지정된 쿼리를 실행합니다. --sql은 원시 SQL을 실행합니다. --data는 결과를 출력하고 --format은 출력 형식(csv, json, table)을 설정합니다.
확인
gtfs-tools validate # GTFS 유효성 검사 실행
gtfs-tools validate --report # 유효성 검사 보고서 생성
gtfs-tools validate --severity error # 오류로 범위 지정
gtfs-tools validate --category pathways # 경로 유효성 검사로 범위 지정
gtfs-tools validate --category schedule # 일정 유효성 검사
gtfs-tools validate --category fare # 요금 유효성 검사
--report는 유효성 검사 보고서를 생성합니다. --severity 및 --category는 유효성 검사를 특정 심각도 또는 범주로 필터링합니다.
상태
gtfs-tools status # 현재 데이터 세트 상태 표시
gtfs-tools status --data # 상태 정보 출력
gtfs-tools status --format json # JSON 형식으로 상태 출력
status는 현재 데이터 세트, 가져온 피드, 만료 날짜를 보여줍니다.
도움말
gtfs-tools help # 일반 도움말
gtfs-tools help import # 가져오기 명령어 도움말
gtfs-tools import -h # 가져오기 명령어 도움말 (약식)
gtfs-tools h export # 내보내기 명령어 도움말
gtfs-tools h edit # 편집 명령어 도움말
추가 정보
- 데이터는
~/.gtfs-viz-cli/에 저장됩니다. - 데이터 세트는 7일 후 만료됩니다.
- 가져오기는 일회성입니다. 새 가져오기는 현재 데이터 세트를 대체합니다.
- 대시보드는 로컬 웹 서버에서 실행됩니다.
- 명령어는 기본적으로 대시보드를 엽니다. 행 출력에는
--data를 사용하세요. - JSON 출력에는
--format json을 사용하세요.