gabrielAHN/gtfs-tools

GTFS Tools CLI

Importieren Sie GTFS-Feeds, fragen Sie Transitdaten ab, durchsuchen Sie Routen/Fahrten/Kalender/Formen, vergleichen Sie Fahrpläne, bearbeiten Sie Stationen/Wege/Routen/Fahrten/Haltestellenzeiten, exportieren Sie Änderungen oder öffnen Sie das lokale Dashboard.

Referenzdateien

Lesen Sie diese, wenn Sie genaue Spaltennamen, SQL-Syntax oder Flag-Details benötigen:

• references/commands.md — Alle CLI-Befehle mit Flags und Beispielen
• references/edits.md — Fahrten-/Fahrplan-/Servicebearbeitungen anwenden und das Changeset-Format zur Übergabe von Serviceänderungen an die CLI
• references/tables.md — Tabellen- und Ansichtsschemata mit Spaltentypen
• gtfs-Erweiterung Funktionsreferenz — jede SQL-Funktion mit einem ausführbaren Beispiel (Markdown)
• GTFS Tools CLI-Dokumentation und der Dokumentationsindex — jede Dokumentationsseite als Markdown
• references/gtfs-schedule-reference.md — GTFS-Fahrplan-Feldreferenz mit Fokus auf Stationskomponenten, Wege und Audits zu fehlenden Verbindungen
• references/examples.sql — Praktische SQL-Abfragebeispiele

Installieren

Installieren Sie die CLI global und registrieren Sie das Skill:

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

Oder installieren Sie nur das Skill über npx:

npx skills add gabrielAHN/gtfs-tools

Verwenden Sie anthropic, openai, google oder generic für den KI-Anbieter. Führen Sie gtfs-tools install-skill --list-providers aus, um die aufgelösten Installationspfade zu sehen. --provider <name> entspricht dem positionellen Anbieternamen, und --target-dir <dir> überschreibt den Standard. Die nicht-interaktive Nutzung erfordert dennoch einen Anbieter, wenn --target-dir gesetzt ist. Ein älteres gtfs-viz-Skill-Verzeichnis daneben bleibt erhalten und wird als veraltet gemeldet; entfernen Sie es selbst, sobald dieses Skill installiert ist.

Verwenden Sie gtfs-tools h für allgemeine Hilfe oder gtfs-tools h <command> für die gleiche befehlsspezifische Hilfe wie gtfs-tools help <command> und gtfs-tools <command> -h.

Zeigen Sie die installierte CLI an oder aktualisieren Sie sie:

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

update bewahrt den importierten Datensatz und die Sitzung. Fügen Sie --provider hinzu, um das installierte Skill für diesen Anbieter nach dem CLI-Update zu aktualisieren.

Aus einem Checkout von gabrielAHN/gtfs-tools:

npm ci
npm run build
npm install -g .

Schnellstart

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

Importieren

gtfs-tools import /absoluter/pfad/zu/feed.zip
gtfs-tools import https://example.com/gtfs/feed.zip
gtfs-tools import s3://my-bucket/gtfs/feed.zip      # auch s3a://, s3n://
gtfs-tools import r2://my-bucket/gtfs/feed.zip

Verwenden Sie einfache oder in Anführungszeichen gesetzte Pfade oder URLs. Verwenden Sie keine Backticks. Der Import ist einmalig; ein neuer Import ersetzt den aktuellen Datensatz. Daten werden unter ~/.gtfs-viz-cli/current gespeichert. Datensätze laufen automatisch nach 7 Tagen ab.

Remote-Feeds werden zunächst nach ~/.gtfs-viz-cli/downloads/ heruntergeladen, müssen ein Zip-Archiv sein und werden nach dem Import gelöscht. Download- und Validierungsfehler (kein Zip, keine stops.txt) lassen den aktuellen Datensatz unberührt; ein Fehler während des DuckDB-Imports selbst löscht ihn dennoch, wie bei lokalen Dateien. Abfragezeichenfolgen (pre-signed URLs) werden für den Download verwendet, aber niemals gespeichert oder ausgegeben. URLs mit eingebettetem Benutzernamen oder Passwort werden abgelehnt, und andere Schemata (gs://, az://, hf://, …) werden nicht unterstützt. Ein nicht kodiertes @ in einem http(s)-URL-Pfad wird ebenfalls abgelehnt: Kodieren Sie es als %40, und setzen Sie niemals Anmeldeinformationen in eine URL.

s3://- und r2://-Objekte authentifizieren sich über DuckDB-Secrets: zuerst ein passendes Secret (einschließlich persistenter Secrets, z.B. duckdb -c "CREATE PERSISTENT SECRET (TYPE s3, KEY_ID '…', SECRET '…', REGION 'us-east-1')"); dann, für s3://, AWS-Umgebungsvariablen, ein AWS-Profil oder SSO über ein temporäres credential_chain-Secret; danach eine anonyme Anfrage. r2:// benötigt CREATE PERSISTENT SECRET (TYPE r2, KEY_ID '…', SECRET '…', ACCOUNT_ID '…'). MinIO und andere S3-kompatible Speicher verwenden ein s3-Secret mit ENDPOINT, URL_STYLE 'path' und USE_SSL. Fragen Sie den Benutzer niemals, Geheimniswerte in einen von Ihnen ausgeführten Befehl einzufügen; bitten Sie ihn, das Geheimnis selbst zu erstellen.

Durchsuchen & Filtern

Filtern Sie Stationen oder Haltestellen direkt in der CLI:

gtfs-tools stations                                # Alle Stationen
gtfs-tools stations --name "Park"                  # Name enthält "Park"
gtfs-tools stations --pathways "no"                # Keine Wege
gtfs-tools stations --wheelchair "accessible"      # Barrierefrei
gtfs-tools stations --station-id place-pktrm       # Exakte ID
gtfs-tools stations --name "Park" --pathways "yes" # Kombiniert

gtfs-tools stops                                   # Alle eigenständigen Haltestellen
gtfs-tools stops --name "Albany"                   # Name enthält "Albany"
gtfs-tools stops --location-type "Stop"            # Nach Typ
gtfs-tools stops --wheelchair "unknown"            # Nach Rollstuhlstatus

gtfs-tools trips                                   # Fahrtenansicht öffnen
gtfs-tools trips --route R1 --data                 # Fahrten für eine Route
gtfs-tools trip trip-123 --data                    # Haltestellenzeiten für eine Fahrt
gtfs-tools trip trip-123 --view timeline           # Zeitleistenansicht öffnen
gtfs-tools trip trip-123 --compare trip-456        # Zwei Fahrten vergleichen

gtfs-tools calendar --data                         # Alle Dienste auflisten
gtfs-tools calendar SAT-1 --data                   # Kalender für einen Dienst

gtfs-tools shapes --data                           # Alle Formen auflisten
gtfs-tools shapes shape-123 --data                 # Punkte für eine Form

Fügen Sie --format json für JSON-Ausgabe hinzu.

Dashboard

Befehle öffnen standardmäßig das Dashboard. Fügen Sie --data hinzu, um Zeilen stattdessen auszugeben.

gtfs-tools station "Park Street"                    # Öffnet Stationsinfo
gtfs-tools station "Park Street" --data             # Gibt Zeilen aus
gtfs-tools stop-info "Trade Center"                 # Öffnet Haltestellenkarte mit Popup + Zoom
gtfs-tools station_connections "Park Street"         # Öffnet Flussdiagramm
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

Geben Sie die Dashboard-URL an den Benutzer zurück.

Stationssuche

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

Verwenden Sie --station-id oder --station-name, wenn der Werttyp bekannt ist. Verwenden Sie --selected-station oder das positionelle Argument, wenn es beides sein könnte.

Wege & Verbindungen

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 zielt auf Bahnsteige, Ausgänge/Eingänge oder Wegknoten innerhalb einer Station.

Wenn Sie nach fehlenden Stationskomponenten oder unterbrochener interner Konnektivität suchen, verwenden Sie nur Stationskomponenten- und Netzwerkfunktionen. Beginnen Sie mit get_station_stops(station_id), überprüfen Sie dann get_station_pathways(station_id), get_station_routes(station_id), find_shortest_path oder find_reachable_stops. Prüfen Sie die interne Konnektivität einer Station nicht von StopsTable aus, da diese Tabelle für eigenständige Haltestellen ist. Siehe references/gtfs-schedule-reference.md.

Routen & Service

gtfs-tools routes                                   # Alle Routen auflisten
gtfs-tools routes --type Bus                        # Nach Typ filtern
gtfs-tools routes --route-name "Metro"              # Nach Name filtern
gtfs-tools routes --route-id ROUTE_ID               # Nach ID filtern
gtfs-tools route "Line 1"                           # Routeninfo öffnen
gtfs-tools route --route-id ROUTE_ID --data         # Routendaten ausgeben
gtfs-tools route "Line 1" --view service            # Serviceansicht öffnen

Fahrten & Haltestellenzeiten

gtfs-tools trips --data                             # Alle Fahrten auflisten
gtfs-tools trips --route R1 --data                  # Fahrten für eine Route
gtfs-tools trip trip-123 --data                     # Haltestellenzeiten mit Haltestellennamen
gtfs-tools trip trip-123 --data --view info          # Fahrtenmetadaten
gtfs-tools trip trip-123 --view timeline             # Zeitleistenansicht öffnen
gtfs-tools trip trip-123 --view map                  # Kartenansicht öffnen
gtfs-tools trip trip-123 --compare trip-456 --data   # Haltestellenzeiten vergleichen
gtfs-tools trip trip-123 --compare trip-456,trip-789 --view map # 3 Fahrten auf Karte vergleichen
gtfs-tools trips --compare trip-1,trip-2,trip-3      # Fahrten im Dashboard vergleichen

Ansichten: timetable (Standard), timeline (Zeitdiagramm), map (Ort), info (Metadaten mit --data).

Kalender & Formen

gtfs-tools calendar --data                          # Dienste mit Fahrtenanzahl auflisten
gtfs-tools calendar --route R1 --data               # Dienste für eine Route
gtfs-tools calendar SAT-1 --data                    # Kalender + Daten für einen Dienst
gtfs-tools shapes --data                            # Formen mit Punktanzahl auflisten
gtfs-tools shapes --route R1 --data                 # Formen für eine Route
gtfs-tools shapes shape-123 --data                  # Punkte für eine Form

Routenlinienbänder

gtfs-tools route-bands                              # Parallele Routenlinienbänder erstellen (Separate Route(s))
gtfs-tools route-bands --data                       # band_rows, routes, widest_bundle ausgeben
gtfs-tools route-bands --status --data              # Vorhandene Bandanzahl melden, ohne neu zu erstellen

Erstellt RouteShapeBandsTable allein aus den GTFS-shapes: Routen, die sich einen Korridor teilen, werden auf eine Mittellinie konvergiert und mit seitlichen Spuren versehen, damit die Separate-Route(s)-Ansicht des Dashboards sie als parallele Bänder zeichnet. Verwenden Sie dies anstelle von query, um die Korridor-Makros auszuführen – sie benötigen eine beschreibbare räumliche Sitzung.

Stationsrouten & Pfadfindung

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 findet die schnellste Eingang-zu-Ausgang-Route nach Zeit.

Datenbearbeitung (Verbindungen)

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

Wegmodi: 1=Gehweg, 2=Treppen, 3=Rollsteig, 4=Rolltreppe, 5=Aufzug, 6=Tarifschranke, 7=Ausgangsschranke.

Finden Sie zuerst Weg-IDs:

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%'"

Datenbearbeitung (Knoten)

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 "Neuer Eingang" --lat 42.35 --lon -71.06 --location-type "Exit/Entrance" --parent-station place-pktrm
gtfs-tools update_node --stop-id NODE_ID --stop-name "Hauptlobby"
gtfs-tools delete_node --stop-id NODE_ID

Standorttypen: Station, Stop, Exit/Entrance, Generic Node, Boarding Area.

Finden Sie zuerst Haltestellen-IDs:

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

Fahrten, Fahrpläne & Service bearbeiten

Wenden Sie Serviceänderungen (z.B. von einer Alarmseite) auf den importierten Feed an. Die CLI liest keine Alarme – Sie übersetzen die Änderung in Bearbeitungen. Siehe references/edits.md für das vollständige Changeset-Format, den Lesen → Prüfen → Bestätigen → Implementieren → Überprüfen-Workflow und das Alarmvalidierungs- Berichtsformat (In-Daten-Status + Alarmbeschreibung + Quelllink + ein klickbarer, CLI-validierter Dashboard-Link). Es behandelt auch das Umleiten einer Fahrt auf eine andere Linie (z.B. "A/C fährt via F") mit gtfs-tools reroute – das die Haltestellen der Spenderroute mit skalierter Taktung einfügt, anstatt nur Haltestellen auszulassen – und das Anzeigen mit gtfs-tools trip <id> --compare <spender_fahrt> --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"        # nur angegebene Felder ändern
gtfs-tools delete_trip --trip-id T2                             # kaskadiert zu 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   # betroffene Fahrt direkt im Umleitungsformular öffnen
gtfs-tools reroute --trip A_TRIP --via F_TRIP --from "W 4 St-Wash Sq" --to "Jay St-MetroTech"   # A via F zwischen diesen Haltestellen fahren
gtfs-tools remove_stops --trip T2 --stops "Spring St,Canal St"                # überspringen/express, Stationsumfahrung
gtfs-tools truncate_trip --trip T2 --to "14 St"                                # vorzeitige Wendung / endet früh
gtfs-tools split_trip --trip T2 --gap-from "Crescent St" --gap-to "Broadway Junction" --new-trip-id T2_SEC2  # Zweiteilung

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=hinzufügen, 2=Service an diesem Datum entfernen
gtfs-tools delete_cal

…

[gekürzt zur Übersetzung]