CLI de GTFS Tools
Importa feeds GTFS, consulta datos de tránsito, navega por rutas/viajes/calendarios/formas, compara horarios de viajes, edita estaciones/conexiones/rutas/viajes/horarios, exporta cambios o abre el panel de control local.
Archivos de Referencia
Lee estos cuando necesites nombres de columna exactos, sintaxis SQL o detalles de banderas:
- referencias/commands.md — Todos los comandos CLI con banderas y ejemplos
- referencias/edits.md — Aplica ediciones de viaje/horario/servicio y el formato de changeset para alimentar cambios de servicio a la CLI
- referencias/tables.md — Esquemas de tablas y vistas con tipos de columna
gtfsreferencia de funciones de extensión — cada función SQL con un ejemplo ejecutable (markdown)- Documentación de CLI de GTFS Tools y el índice de documentación — cada página de documentación como markdown
- referencias/gtfs-schedule-reference.md — Referencia de campo de horario GTFS enfocada en partes de estaciones, conexiones y auditorías de conexiones faltantes
- referencias/examples.sql — Ejemplos prácticos de consultas SQL
Instalación
Instala la CLI globalmente y registra la habilidad:
npm install -g @gabrielahn/gtfs-tools
gtfs-tools install-skill openai
O instala solo la habilidad mediante npx:
npx skills add gabrielAHN/gtfs-tools
Usa anthropic, openai, google o generic para el proveedor de IA. Ejecuta gtfs-tools install-skill --list-providers para ver las rutas de instalación resueltas. --provider <nombre> es equivalente al nombre del proveedor posicional, y --target-dir <dir> anula el directorio predeterminado. El uso no interactivo aún requiere un proveedor cuando se establece --target-dir. Un directorio de habilidad gtfs-viz antiguo al lado se deja en su lugar y se informa como obsoleto; elimínalo tú mismo una vez que esta habilidad esté instalada.
Usa gtfs-tools h para ayuda general o gtfs-tools h <comando> para la misma ayuda específica del comando que gtfs-tools help <comando> y gtfs-tools <comando> -h.
Muestra o actualiza la CLI instalada:
gtfs-tools --version
gtfs-tools update --check
gtfs-tools update
gtfs-tools update --provider openai
update conserva el conjunto de datos importado y la sesión. Añade --provider para actualizar la habilidad instalada para ese proveedor después de la actualización de la CLI.
Desde un clon de gabrielAHN/gtfs-tools:
npm ci
npm run build
npm install -g .
Inicio Rápido
gtfs-tools import /ruta/al/feed.zip
gtfs-tools status
gtfs-tools stations
gtfs-tools station "Park Street"
gtfs-tools station_pathways "Park Street" --data
Importación
gtfs-tools import /ruta/absoluta/al/feed.zip
gtfs-tools import https://ejemplo.com/gtfs/feed.zip
gtfs-tools import s3://mi-bucket/gtfs/feed.zip # también s3a://, s3n://
gtfs-tools import r2://mi-bucket/gtfs/feed.zip
Usa rutas o URLs simples o entrecomilladas. No uses acentos graves. La importación es de una sola vez; una nueva importación reemplaza el conjunto de datos actual. Los datos se almacenan en ~/.gtfs-viz-cli/current. Los conjuntos de datos caducan automáticamente después de 7 días.
Los feeds remotos se descargan primero en ~/.gtfs-viz-cli/downloads/, deben ser un archivo zip y se eliminan después de la importación. Las fallas de descarga y validación (no es un zip, no tiene stops.txt) dejan el conjunto de datos actual intacto; una falla durante la importación de DuckDB en sí lo borra, al igual que para archivos locales. Las cadenas de consulta (URLs prefirmadas) se usan para la descarga pero nunca se almacenan ni imprimen. Las URLs con un nombre de usuario o contraseña incrustados son rechazadas, y otros esquemas (gs://, az://, hf://, …) no son compatibles. Una @ sin codificar en una ruta de URL http(s) también es rechazada: codifícala como %40, y nunca pongas credenciales en una URL.
Los objetos s3:// y r2:// se autentican a través de secretos de DuckDB: primero cualquier secreto coincidente (incluyendo los persistentes, ej. duckdb -c "CREATE PERSISTENT SECRET (TYPE s3, KEY_ID '…', SECRET '…', REGION 'us-east-1')"); luego, para s3://, variables de entorno de AWS, un perfil de AWS o SSO a través de un secreto temporal credential_chain; luego una solicitud anónima. r2:// necesita CREATE PERSISTENT SECRET (TYPE r2, KEY_ID '…', SECRET '…', ACCOUNT_ID '…'). MinIO y otros almacenes compatibles con S3 usan un secreto s3 con ENDPOINT, URL_STYLE 'path' y USE_SSL. Nunca le pidas al usuario que pegue valores secretos en un comando que ejecutes; pídele que cree el secreto ellos mismos.
Explorar y Filtrar
Filtra estaciones o paradas directamente en la CLI:
gtfs-tools stations # Todas las estaciones
gtfs-tools stations --name "Park" # El nombre contiene "Park"
gtfs-tools stations --pathways "no" # Sin conexiones
gtfs-tools stations --wheelchair "accessible" # Accesible
gtfs-tools stations --station-id place-pktrm # ID exacto
gtfs-tools stations --name "Park" --pathways "yes" # Combinado
gtfs-tools stops # Todas las paradas independientes
gtfs-tools stops --name "Albany" # El nombre contiene "Albany"
gtfs-tools stops --location-type "Stop" # Por tipo
gtfs-tools stops --wheelchair "unknown" # Por estado de accesibilidad
gtfs-tools trips # Vista de viajes abierta
gtfs-tools trips --route R1 --data # Viajes para una ruta
gtfs-tools trip trip-123 --data # Horarios de parada para un viaje
gtfs-tools trip trip-123 --view timeline # Abre vista de línea de tiempo
gtfs-tools trip trip-123 --compare trip-456 # Compara dos viajes
gtfs-tools calendar --data # Lista todos los servicios
gtfs-tools calendar SAT-1 --data # Calendario para un servicio
gtfs-tools shapes --data # Lista todas las formas
gtfs-tools shapes shape-123 --data # Puntos para una forma
Añade --format json para salida JSON.
Panel de Control
Los comandos abren el panel de control de forma predeterminada. Añade --data para imprimir filas en su lugar.
gtfs-tools station "Park Street" # Abre información de la estación
gtfs-tools station "Park Street" --data # Imprime filas
gtfs-tools stop-info "Trade Center" # Abre mapa de parada con ventana emergente + zoom
gtfs-tools station_connections "Park Street" # Abre gráfico de flujo
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
Devuelve la URL del panel de control impresa al usuario.
Consulta de Estaciones
gtfs-tools station "Park Street"
gtfs-tools station --id place-pktrm --data
gtfs-tools station --id place-pktrm --format json
Usa --station-id o --station-name cuando se conozca el tipo de valor. Usa --selected-station o el argumento posicional cuando podría ser cualquiera.
Conexiones y Rutas Internas
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 apunta a plataformas, salidas/entradas o nodos de ruta dentro de una estación.
Al verificar partes faltantes de la estación o conectividad interna rota, usa solo funciones de partes de estación y red. Comienza con get_station_stops(station_id), luego inspecciona get_station_pathways(station_id), get_station_routes(station_id), find_shortest_path o find_reachable_stops. No audites la conectividad interna de la estación desde StopsTable, porque esa tabla es para paradas independientes. Consulta referencias/gtfs-schedule-reference.md.
Rutas y Servicio
gtfs-tools routes # Lista todas las rutas
gtfs-tools routes --type Bus # Filtra por tipo
gtfs-tools routes --route-name "Metro" # Filtra por nombre
gtfs-tools routes --route-id ROUTE_ID # Filtra por ID
gtfs-tools route "Line 1" # Abre información de la ruta
gtfs-tools route --route-id ROUTE_ID --data # Imprime datos de la ruta
gtfs-tools route "Line 1" --view service # Abre vista de servicio
Viajes y Horarios de Parada
gtfs-tools trips --data # Lista todos los viajes
gtfs-tools trips --route R1 --data # Viajes para una ruta
gtfs-tools trip trip-123 --data # Horarios de parada con nombres de parada
gtfs-tools trip trip-123 --data --view info # Metadatos del viaje
gtfs-tools trip trip-123 --view timeline # Abre vista de línea de tiempo
gtfs-tools trip trip-123 --view map # Abre vista de mapa
gtfs-tools trip trip-123 --compare trip-456 --data # Compara horarios de parada
gtfs-tools trip trip-123 --compare trip-456,trip-789 --view map # Compara 3 viajes en el mapa
gtfs-tools trips --compare trip-1,trip-2,trip-3 # Compara viajes en el panel de control
Vistas: timetable (predeterminada), timeline (gráfico de tiempo), map (ubicación), info (metadatos con --data).
Calendario y Formas
gtfs-tools calendar --data # Lista servicios con conteos de viajes
gtfs-tools calendar --route R1 --data # Servicios para una ruta
gtfs-tools calendar SAT-1 --data # Calendario + fechas para un servicio
gtfs-tools shapes --data # Lista formas con conteos de puntos
gtfs-tools shapes --route R1 --data # Formas para una ruta
gtfs-tools shapes shape-123 --data # Puntos para una forma
Bandas de Línea de Ruta
gtfs-tools route-bands # Construye bandas de línea de ruta paralelas (Separate Route(s))
gtfs-tools route-bands --data # Imprime band_rows, rutas, widest_bundle
gtfs-tools route-bands --status --data # Reporta conteos de bandas existentes sin reconstruir
Construye RouteShapeBandsTable a partir de las shapes de GTFS solamente: las rutas que comparten un corredor se convergen en una línea central y se les asignan carriles laterales para que la vista Separate Route(s) del panel de control las dibuje como bandas paralelas. Usa esto en lugar de query para ejecutar las macros de corredor, ya que necesitan una sesión espacial escribible.
Rutas de Estación y Búsqueda de Rutas
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 encuentra la ruta más rápida de entrada a salida por tiempo.
Edición de Datos (Conexiones)
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
Modos de conexión: 1=pasillo, 2=escaleras, 3=acera móvil, 4=escalera mecánica, 5=ascensor, 6=puerta de tarifa, 7=puerta de salida.
Encuentra los ID de conexión primero:
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%'"
Edición de Datos (Nodos)
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
Tipos de ubicación: Station, Stop, Exit/Entrance, Generic Node, Boarding Area.
Encuentra los ID de parada primero:
gtfs-tools query --name station-stops --args-json '{"stationId":"place-pktrm"}' --data
Edición de Viajes, Horarios y Servicio
Aplica cambios de servicio (ej. desde una página de alertas) al feed importado. La CLI no lee alertas — tú traduces el cambio a ediciones. Consulta referencias/edits.md para el formato completo de changeset, el flujo de trabajo de leer → verificar → confirmar → implementar → revisar, y el formato del informe de validación de alertas (estado en datos + descripción de alerta + enlace de origen + un enlace al panel de control verificable y cliqueable por CLI). También cubre redirigir un viaje a otra línea (ej. "A/C corre por la F") con gtfs-tools reroute — que inserta las paradas de la ruta donante con tiempos escalados en lugar de solo saltarse paradas — y visualizarlo con 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" # solo cambian los campos dados
gtfs-tools delete_trip --trip-id T2 # se propaga a 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 # abre el viaje afectado directamente en el formulario de redirección
gtfs-tools reroute --trip A_TRIP --via F_TRIP --from "W 4 St-Wash Sq" --to "Jay St-MetroTech" # ejecuta A por la F entre esas paradas
gtfs-tools remove_stops --trip T2 --stops "Spring St,Canal St" # salte/expreso, desvío de estación
gtfs-tools truncate_trip --trip T2 --to "14 St" # gira temprano / termina antes
gtfs-tools split_trip --trip T2 --gap-from "Crescent St" --gap-to "Broadway Junction" --new-trip-id T2_SEC2 # división en dos secciones
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=añadir, 2=eliminar servicio en fecha
gtfs-tools delete_cal
…
[truncado para traducción]