CLI GTFS Tools
Importer des flux GTFS, interroger les données de transport, parcourir les itinéraires/voyages/calendriers/formes, comparer les horaires de voyage, modifier les stations/passages/itinéraires/voyages/horaires, exporter les modifications ou ouvrir le tableau de bord local.
Fichiers de référence
Lisez ces fichiers lorsque vous avez besoin des noms de colonnes exacts, de la syntaxe SQL ou des détails des options :
- references/commands.md — Toutes les commandes CLI avec options et exemples
- references/edits.md — Appliquer les modifications de voyage / planning / service et le format de jeu de modifications pour alimenter les changements de service dans la CLI
- references/tables.md — Schémas des tables et vues avec les types de colonnes
- Référence des fonctions d'extension
gtfs— Chaque fonction SQL avec un exemple exécutable (markdown) - Documentation de la CLI GTFS Tools et l'index de la documentation — Chaque page de documentation en markdown
- references/gtfs-schedule-reference.md — Référence des champs GTFS Schedule axée sur les parties de station, les passages et les audits de connexions manquantes
- references/examples.sql — Exemples pratiques de requêtes SQL
Installation
Installer la CLI globalement et enregistrer la compétence :
npm install -g @gabrielahn/gtfs-tools
gtfs-tools install-skill openai
Ou installer uniquement la compétence via npx :
npx skills add gabrielAHN/gtfs-tools
Utilisez anthropic, openai, google ou generic pour le fournisseur d'IA. Exécutez gtfs-tools install-skill --list-providers pour voir les chemins d'installation résolus. --provider <name> est équivalent au nom du fournisseur positionnel, et --target-dir <dir> remplace la valeur par défaut. L'utilisation non interactive nécessite toujours un fournisseur lorsque --target-dir est défini. Un ancien répertoire de compétence gtfs-viz à côté est laissé en place et signalé comme obsolète ; supprimez-le vous-même une fois cette compétence installée.
Utilisez gtfs-tools h pour l'aide générale ou gtfs-tools h <commande> pour la même aide spécifique à une commande que gtfs-tools help <commande> et gtfs-tools <commande> -h.
Afficher ou mettre à jour la CLI installée :
gtfs-tools --version
gtfs-tools update --check
gtfs-tools update
gtfs-tools update --provider openai
update préserve le jeu de données importé et la session. Ajoutez --provider pour rafraîchir la compétence installée pour ce fournisseur après la mise à jour de la CLI.
À partir d'un checkout de gabrielAHN/gtfs-tools :
npm ci
npm run build
npm install -g .
Démarrage rapide
gtfs-tools import /chemin/vers/flux.zip
gtfs-tools status
gtfs-tools stations
gtfs-tools station "Park Street"
gtfs-tools station_pathways "Park Street" --data
Importation
gtfs-tools import /chemin/absolu/vers/flux.zip
gtfs-tools import https://exemple.com/gtfs/flux.zip
gtfs-tools import s3://mon-bucket/gtfs/flux.zip # aussi s3a://, s3n://
gtfs-tools import r2://mon-bucket/gtfs/flux.zip
Utilisez des chemins ou des URL simples ou entre guillemets. N'utilisez pas d'accents graves. L'importation est unique ; une nouvelle importation remplace le jeu de données actuel. Les données sont stockées dans ~/.gtfs-viz-cli/current. Les jeux de données expirent automatiquement après 7 jours.
Les flux distants sont d'abord téléchargés dans ~/.gtfs-viz-cli/downloads/, doivent être une archive zip et sont supprimés après l'importation. Les échecs de téléchargement et de validation (pas un zip, pas de stops.txt) laissent le jeu de données actuel intact ; un échec lors de l'importation DuckDB elle-même l'efface toujours, comme pour les fichiers locaux. Les chaînes de requête (URL pré-signées) sont utilisées pour le téléchargement mais jamais stockées ni imprimées. Les URL avec un nom d'utilisateur ou un mot de passe intégré sont refusées, et les autres schémas (gs://, az://, hf://, …) ne sont pas pris en charge. Un @ non encodé dans un chemin d'URL http(s) est également refusé : encodez-le en %40, et ne mettez jamais d'informations d'identification dans une URL.
Les objets s3:// et r2:// s'authentifient via les secrets DuckDB : d'abord tout secret correspondant (y compris les secrets persistants, par exemple duckdb -c "CREATE PERSISTENT SECRET (TYPE s3, KEY_ID '…', SECRET '…', REGION 'us-east-1')") ; puis, pour s3://, les variables d'environnement AWS, un profil AWS ou SSO via un secret temporaire credential_chain ; puis une requête anonyme. r2:// nécessite CREATE PERSISTENT SECRET (TYPE r2, KEY_ID '…', SECRET '…', ACCOUNT_ID '…'). MinIO et autres magasins compatibles S3 utilisent un secret s3 avec ENDPOINT, URL_STYLE 'path' et USE_SSL. Ne demandez jamais à l'utilisateur de coller des valeurs secrètes dans une commande que vous exécutez ; demandez-lui de créer le secret lui-même.
Navigation & Filtrage
Filtrer les stations ou les arrêts directement dans la CLI :
gtfs-tools stations # Toutes les stations
gtfs-tools stations --name "Park" # Le nom contient "Park"
gtfs-tools stations --pathways "no" # Aucun passage
gtfs-tools stations --wheelchair "accessible" # Accessible
gtfs-tools stations --station-id place-pktrm # ID exact
gtfs-tools stations --name "Park" --pathways "yes" # Combiné
gtfs-tools stops # Tous les arrêts autonomes
gtfs-tools stops --name "Albany" # Le nom contient "Albany"
gtfs-tools stops --location-type "Stop" # Par type
gtfs-tools stops --wheelchair "unknown" # Par statut d'accessibilité
gtfs-tools trips # Ouvrir la vue des voyages
gtfs-tools trips --route R1 --data # Voyages pour un itinéraire
gtfs-tools trip trip-123 --data # Horaires pour un voyage
gtfs-tools trip trip-123 --view timeline # Ouvrir la vue chronologique
gtfs-tools trip trip-123 --compare trip-456 # Comparer deux voyages
gtfs-tools calendar --data # Lister tous les services
gtfs-tools calendar SAT-1 --data # Calendrier pour un service
gtfs-tools shapes --data # Lister toutes les formes
gtfs-tools shapes shape-123 --data # Points pour une forme
Ajoutez --format json pour une sortie JSON.
Tableau de bord
Les commandes ouvrent le tableau de bord par défaut. Ajoutez --data pour imprimer les lignes à la place.
gtfs-tools station "Park Street" # Ouvre les informations de la station
gtfs-tools station "Park Street" --data # Imprime les lignes
gtfs-tools stop-info "Trade Center" # Ouvre la carte de l'arrêt avec popup + zoom
gtfs-tools station_connections "Park Street" # Ouvre le graphe de flux
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
Retournez l'URL du tableau de bord imprimé à l'utilisateur.
Recherche de station
gtfs-tools station "Park Street"
gtfs-tools station --id place-pktrm --data
gtfs-tools station --id place-pktrm --format json
Utilisez --station-id ou --station-name lorsque le type de valeur est connu. Utilisez --selected-station ou l'argument positionnel lorsqu'il pourrait s'agir de l'un ou l'autre.
Passages & Connexions
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 cible les quais, les sorties/entrées ou les nœuds de passage dans une station.
Lors de la vérification des pièces de station manquantes ou de la connectivité interne défaillante, utilisez uniquement les fonctions de partie de station et de réseau. Commencez par get_station_stops(station_id), puis inspectez get_station_pathways(station_id), get_station_routes(station_id), find_shortest_path ou find_reachable_stops. N'auditez pas la connectivité interne de la station à partir de StopsTable, car cette table est destinée aux arrêts autonomes. Voir references/gtfs-schedule-reference.md.
Itinéraires & Service
gtfs-tools routes # Lister tous les itinéraires
gtfs-tools routes --type Bus # Filtrer par type
gtfs-tools routes --route-name "Metro" # Filtrer par nom
gtfs-tools routes --route-id ROUTE_ID # Filtrer par ID
gtfs-tools route "Line 1" # Ouvrir les informations de l'itinéraire
gtfs-tools route --route-id ROUTE_ID --data # Imprimer les données de l'itinéraire
gtfs-tools route "Line 1" --view service # Ouvrir la vue de service
Voyages & Horaires
gtfs-tools trips --data # Lister tous les voyages
gtfs-tools trips --route R1 --data # Voyages pour un itinéraire
gtfs-tools trip trip-123 --data # Horaires avec noms d'arrêts
gtfs-tools trip trip-123 --data --view info # Métadonnées du voyage
gtfs-tools trip trip-123 --view timeline # Ouvrir la vue chronologique
gtfs-tools trip trip-123 --view map # Ouvrir la vue carte
gtfs-tools trip trip-123 --compare trip-456 --data # Comparer les horaires
gtfs-tools trip trip-123 --compare trip-456,trip-789 --view map # Comparer 3 voyages sur la carte
gtfs-tools trips --compare trip-1,trip-2,trip-3 # Comparer les voyages dans le tableau de bord
Vues : timetable (par défaut), timeline (graphique temporel), map (emplacement), info (métadonnées avec --data).
Calendrier & Formes
gtfs-tools calendar --data # Lister les services avec nombre de voyages
gtfs-tools calendar --route R1 --data # Services pour un itinéraire
gtfs-tools calendar SAT-1 --data # Calendrier + dates pour un service
gtfs-tools shapes --data # Lister les formes avec nombre de points
gtfs-tools shapes --route R1 --data # Formes pour un itinéraire
gtfs-tools shapes shape-123 --data # Points pour une forme
Bandes de lignes d'itinéraire
gtfs-tools route-bands # Construire des bandes de lignes d'itinéraire parallèles (Itinéraire(s) séparé(s))
gtfs-tools route-bands --data # Imprimer band_rows, routes, widest_bundle
gtfs-tools route-bands --status --data # Rapporter le nombre de bandes existantes sans reconstruire
Construit RouteShapeBandsTable à partir des shapes GTFS seules : les itinéraires partageant un
couloir sont convergés sur une seule ligne centrale et se voient attribuer des voies latérales afin que
la vue Itinéraire(s) séparé(s) du tableau de bord les dessine comme des bandes parallèles. Utilisez ceci plutôt
que query pour exécuter les macros de couloir — elles nécessitent une session spatiale inscriptible.
Itinéraires de station & Recherche de chemin
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 trouve l'itinéraire le plus rapide d'une entrée à une sortie en fonction du temps.
Édition de données (Connexions)
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
Modes de passage : 1=passage piéton, 2=escalier, 3=trottoir roulant, 4=escalator, 5=ascenseur, 6=portillon, 7=porte de sortie.
Trouvez d'abord les ID de passage :
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%'"
Édition de données (Nœuds)
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
Types d'emplacement : Station, Stop, Exit/Entrance, Generic Node, Boarding Area.
Trouvez d'abord les ID d'arrêt :
gtfs-tools query --name station-stops --args-json '{"stationId":"place-pktrm"}' --data
Édition des voyages, plannings & services
Appliquez les modifications de service (par exemple, à partir d'une page d'alertes) au flux importé. La CLI ne lit pas les alertes
— vous traduisez le changement en modifications. Voir references/edits.md pour le format complet du jeu de modifications, le workflow lire → vérifier → confirmer → implémenter → réviser, et le format du rapport de validation des alertes (statut dans les données + description de l'alerte + lien source + un lien de tableau de bord cliquable et validé par la CLI). Il couvre également le réacheminement d'un voyage sur une autre ligne (par exemple, "A/C roule via le F") avec gtfs-tools reroute — qui insère les arrêts de l'itinéraire donneur avec un timing mis à l'échelle plutôt que de simplement sauter des arrêts — et la visualisation avec 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" # seuls les champs donnés changent
gtfs-tools delete_trip --trip-id T2 # se propage aux 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 # ouvrir le voyage concerné directement dans le formulaire de réacheminement
gtfs-tools reroute --trip A_TRIP --via F_TRIP --from "W 4 St-Wash Sq" --to "Jay St-MetroTech" # faire circuler A via le F entre ces arrêts
gtfs-tools remove_stops --trip T2 --stops "Spring St,Canal St" # saut/express, contournement de station
gtfs-tools truncate_trip --trip T2 --to "14 St" # court tour / se termine plus tôt
gtfs-tools split_trip --trip T2 --gap-from "Crescent St" --gap-to "Broadway Junction" --new-trip-id T2_SEC2 # scission en deux sections
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=ajouter, 2=supprimer le service à la date
gtfs-tools delete_calendar_date --service-id WKD --date 20260906
gtfs-tools query --sql "SELECT * FROM CalendarDatesTable WHERE service_id = 'WKD'"
## Export et sauvegarde
gtfs-tools export --dir /chemin/vers/export # Exporter toutes les tables en CSV
gtfs-tools export --dir /chemin/vers/export --format geojson # Exporter en GeoJSON
gtfs-tools export --tables stops,routes,trips --dir /chemin/vers/export
gtfs-tools export --tables stops --format json --dir /chemin/vers/export
gtfs-tools export --summary --dir /chemin/vers/export # Exporter un résumé en JSON
gtfs-tools export --db --dir /chemin/vers/export # Exporter la base DuckDB complète
gtfs-tools snapshot # Créer un instantané de l'état actuel
gtfs-tools snapshot --name "avant-modifications" # Avec un nom personnalisé
gtfs-tools snapshots # Lister les instantanés
gtfs-tools restore --name "avant-modifications" # Restaurer un instantané
gtfs-tools restore --latest # Restaurer le dernier instantané
## Requêtes SQL
gtfs-tools query --sql "SELECT trip_id, count(*) FROM StopTimesTable GROUP BY trip_id LIMIT 10"
gtfs-tools query --sql "SELECT * FROM StopsTable WHERE parent_station = 'place-pktrm'" --format json
gtfs-tools query --name station-stops --args-json '{"stationId":"place-pktrm"}' --data
gtfs-tools query --name unconnected-stops --data
gtfs-tools query --list # Lister les requêtes nommées disponibles
gtfs-tools query --name unconnected-stops --sql "SELECT * FROM StopsTable WHERE parent_station IS NULL AND location_type = 0" # Enregistrer une nouvelle requête
gtfs-tools query --delete unconnected-stops # Supprimer une requête nommée
## Journal des modifications
gtfs-tools log # Afficher les modifications récentes
gtfs-tools log --limit 20 # Avec une limite
gtfs-tools log --format json # En JSON
gtfs-tools undo # Annuler la dernière modification
gtfs-tools redo # Rétablir la dernière annulation
## Aide & Informations
gtfs-tools --version
gtfs-tools h
gtfs-tools h import
gtfs-tools help stations
gtfs-tools station --help