CLI GTFS Tools
Importe feeds GTFS, consulte dados de trânsito, navegue por rotas/viagens/calendários/formas, compare horários de viagens, edite estações/caminhos/rotas/viagens/horários de paradas, exporte alterações ou abra o painel local.
Arquivos de Referência
Leia estes quando precisar de nomes de colunas exatos, sintaxe SQL ou detalhes de flags:
- references/commands.md — Todos os comandos da CLI com flags e exemplos
- references/edits.md — Aplique edições de viagem/horário/serviço e o formato de changeset para alimentar alterações de serviço para a CLI
- references/tables.md — Esquemas de tabelas e visões com tipos de colunas
- Referência de funções da extensão
gtfs— todas as funções SQL com um exemplo executável (markdown) - Documentação da CLI GTFS Tools e o índice da documentação — todas as páginas de documentação em markdown
- references/gtfs-schedule-reference.md — Referência de campo do GTFS Schedule focada em partes de estação, caminhos e auditorias de conexões ausentes
- references/examples.sql — Exemplos práticos de consultas SQL
Instalação
Instale a CLI globalmente e registre a skill:
npm install -g @gabrielahn/gtfs-tools
gtfs-tools install-skill openai
Ou instale apenas a skill via npx:
npx skills add gabrielAHN/gtfs-tools
Use anthropic, openai, google ou generic para o provedor de IA. Execute gtfs-tools install-skill --list-providers para ver os caminhos de instalação resolvidos. --provider <nome> é equivalente ao nome do provedor posicional, e --target-dir <dir> substitui o padrão. O uso não interativo ainda requer um provedor quando --target-dir é definido. Um diretório de skill gtfs-viz mais antigo ao lado é deixado no lugar e relatado como desatualizado; remova-o você mesmo depois que esta skill for instalada.
Use gtfs-tools h para ajuda geral ou gtfs-tools h <comando> para a mesma ajuda específica de comando que gtfs-tools help <comando> e gtfs-tools <comando> -h.
Mostre ou atualize a CLI instalada:
gtfs-tools --version
gtfs-tools update --check
gtfs-tools update
gtfs-tools update --provider openai
update preserva o conjunto de dados importado e a sessão. Adicione --provider para atualizar a skill instalada para aquele provedor após a atualização da CLI.
A partir de um checkout de gabrielAHN/gtfs-tools:
npm ci
npm run build
npm install -g .
Início Rápido
gtfs-tools import /caminho/para/feed.zip
gtfs-tools status
gtfs-tools stations
gtfs-tools station "Park Street"
gtfs-tools station_pathways "Park Street" --data
Importação
gtfs-tools import /caminho/absoluto/para/feed.zip
gtfs-tools import https://exemplo.com/gtfs/feed.zip
gtfs-tools import s3://meu-bucket/gtfs/feed.zip # também s3a://, s3n://
gtfs-tools import r2://meu-bucket/gtfs/feed.zip
Use caminhos ou URLs simples ou entre aspas. Não use crases. A importação é única; uma nova importação substitui o conjunto de dados atual. Os dados são armazenados em ~/.gtfs-viz-cli/current. Os conjuntos de dados expiram automaticamente após 7 dias.
Feeds remotos são baixados primeiro para ~/.gtfs-viz-cli/downloads/, devem ser um arquivo zip e são excluídos após a importação. Falhas de download e validação (não é um zip, sem stops.txt) deixam o conjunto de dados atual intacto; uma falha durante a própria importação do DuckDB ainda o limpa, como para arquivos locais. Strings de consulta (URLs pré-assinadas) são usadas para o download, mas nunca são armazenadas ou impressas. URLs com um nome de usuário ou senha embutidos são recusadas, e outros esquemas (gs://, az://, hf://, …) não são suportados. Um @ não codificado em um caminho de URL http(s) também é recusado: codifique-o como %40 e nunca coloque credenciais em uma URL.
Objetos s3:// e r2:// autenticam através de segredos do DuckDB: primeiro qualquer segredo correspondente (incluindo persistentes, por exemplo, duckdb -c "CREATE PERSISTENT SECRET (TYPE s3, KEY_ID '…', SECRET '…', REGION 'us-east-1')"); então, para s3://, variáveis de ambiente AWS, um perfil AWS ou SSO através de um segredo temporário credential_chain; então uma solicitação anônima. r2:// precisa de CREATE PERSISTENT SECRET (TYPE r2, KEY_ID '…', SECRET '…', ACCOUNT_ID '…'). MinIO e outros armazenamentos compatíveis com S3 usam um segredo s3 com ENDPOINT, URL_STYLE 'path' e USE_SSL. Nunca peça ao usuário para colar valores secretos em um comando que você executa; peça a eles para criar o segredo eles mesmos.
Navegação e Filtragem
Filtre estações ou paradas diretamente na CLI:
gtfs-tools stations # Todas as estações
gtfs-tools stations --name "Park" # Nome contém "Park"
gtfs-tools stations --pathways "no" # Sem caminhos
gtfs-tools stations --wheelchair "accessible" # Acessível
gtfs-tools stations --station-id place-pktrm # ID exato
gtfs-tools stations --name "Park" --pathways "yes" # Combinado
gtfs-tools stops # Todas as paradas independentes
gtfs-tools stops --name "Albany" # Nome contém "Albany"
gtfs-tools stops --location-type "Stop" # Por tipo
gtfs-tools stops --wheelchair "unknown" # Por status de acessibilidade
gtfs-tools trips # Abrir visão de viagens
gtfs-tools trips --route R1 --data # Viagens para uma rota
gtfs-tools trip trip-123 --data # Horários de parada para uma viagem
gtfs-tools trip trip-123 --view timeline # Abrir visão de linha do tempo
gtfs-tools trip trip-123 --compare trip-456 # Comparar duas viagens
gtfs-tools calendar --data # Listar todos os serviços
gtfs-tools calendar SAT-1 --data # Calendário para um serviço
gtfs-tools shapes --data # Listar todas as formas
gtfs-tools shapes shape-123 --data # Pontos para uma forma
Adicione --format json para saída JSON.
Painel
Os comandos abrem o painel por padrão. Adicione --data para imprimir linhas em vez disso.
gtfs-tools station "Park Street" # Abre informações da estação
gtfs-tools station "Park Street" --data # Imprime linhas
gtfs-tools stop-info "Trade Center" # Abre mapa da parada com popup + zoom
gtfs-tools station_connections "Park Street" # Abre gráfico de fluxo
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
Retorne a URL do painel impressa para o usuário.
Consulta de Estação
gtfs-tools station "Park Street"
gtfs-tools station --id place-pktrm --data
gtfs-tools station --id place-pktrm --format json
Use --station-id ou --station-name quando o tipo de valor é conhecido. Use --selected-station ou o argumento posicional quando pode ser qualquer um.
Caminhos e Conexões
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 tem como alvo plataformas, saídas/entradas ou nós de caminho dentro de uma estação.
Ao verificar peças de estação faltantes ou conectividade interna quebrada, use funções de parte de estação e rede apenas. Comece com get_station_stops(station_id), então inspecione get_station_pathways(station_id), get_station_routes(station_id), find_shortest_path ou find_reachable_stops. Não audite a conectividade interna da estação a partir de StopsTable, porque essa tabela é para paradas independentes. Veja references/gtfs-schedule-reference.md.
Rotas e Serviço
gtfs-tools routes # Listar todas as rotas
gtfs-tools routes --type Bus # Filtrar por tipo
gtfs-tools routes --route-name "Metro" # Filtrar por nome
gtfs-tools routes --route-id ROUTE_ID # Filtrar por ID
gtfs-tools route "Line 1" # Abrir informações da rota
gtfs-tools route --route-id ROUTE_ID --data # Imprimir dados da rota
gtfs-tools route "Line 1" --view service # Abrir visão de serviço
Viagens e Horários de Parada
gtfs-tools trips --data # Listar todas as viagens
gtfs-tools trips --route R1 --data # Viagens para uma rota
gtfs-tools trip trip-123 --data # Horários de parada com nomes de parada
gtfs-tools trip trip-123 --data --view info # Metadados da viagem
gtfs-tools trip trip-123 --view timeline # Abrir visão de linha do tempo
gtfs-tools trip trip-123 --view map # Abrir visão de mapa
gtfs-tools trip trip-123 --compare trip-456 --data # Comparar horários de parada
gtfs-tools trip trip-123 --compare trip-456,trip-789 --view map # Comparar 3 viagens no mapa
gtfs-tools trips --compare trip-1,trip-2,trip-3 # Comparar viagens no painel
Visões: timetable (padrão), timeline (gráfico de tempo), map (localização), info (metadados com --data).
Calendário e Formas
gtfs-tools calendar --data # Listar serviços com contagens de viagens
gtfs-tools calendar --route R1 --data # Serviços para uma rota
gtfs-tools calendar SAT-1 --data # Calendário + datas para um serviço
gtfs-tools shapes --data # Listar formas com contagens de pontos
gtfs-tools shapes --route R1 --data # Formas para uma rota
gtfs-tools shapes shape-123 --data # Pontos para uma forma
Faixas de Linha de Rota
gtfs-tools route-bands # Construir faixas de linha de rota paralelas (Separate Route(s))
gtfs-tools route-bands --data # Imprimir band_rows, routes, widest_bundle
gtfs-tools route-bands --status --data # Relatar contagens de faixas existentes sem reconstruir
Constrói RouteShapeBandsTable a partir das shapes do GTFS apenas: rotas que compartilham um
corredor são convergidas em uma linha central e recebem faixas laterais para que a visão
Separate Route(s) do painel as desenhe como faixas paralelas. Use isso em vez
de query para executar as macros de corredor — elas precisam de uma sessão espacial gravável.
Rotas de Estação e Busca de Caminho
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 encontra a rota de entrada para saída mais rápida por tempo.
Edição de Dados (Conexões)
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 caminho: 1=passagem, 2=escadas, 3=calçada rolante, 4=escada rolante, 5=elevador, 6=catraca, 7=portão de saída.
Encontre IDs de caminho primeiro:
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%'"
Edição de Dados (Nós)
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 localização: Estação, Parada, Saída/Entrada, Nó Genérico, Área de Embarque.
Encontre IDs de parada primeiro:
gtfs-tools query --name station-stops --args-json '{"stationId":"place-pktrm"}' --data
Editando Viagens, Horários e Serviço
Aplique alterações de serviço (por exemplo, de uma página de alertas) ao feed importado. A CLI não lê alertas
— você traduz a mudança em edições. Veja references/edits.md para o formato
completo do changeset, o fluxo de trabalho de ler → verificar → confirmar → implementar → revisar, e o
formato do relatório de validação de alertas (status nos dados + descrição do alerta + link de origem + um link de painel clicável e validado pela CLI). Também cobre redirecionamento de uma viagem para outra linha (por exemplo, "A/C via o F") com
gtfs-tools reroute— que insere as paradas da rota doadora com temporização escalada, em vez de apenas pular paradas — e visualizá-la comgtfs-tools trip --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" # apenas os campos fornecidos mudam
gtfs-tools delete_trip --trip-id T2 # cascateia para 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 a viagem afetada diretamente no formulário de redirecionamento
gtfs-tools reroute --trip A_TRIP --via F_TRIP --from "W 4 St-Wash Sq" --to "Jay St-MetroTech" # executa A via o F entre essas paradas
gtfs-tools remove_stops --trip T2 --stops "Spring St,Canal St" # skip/express, desvio de estação
gtfs-tools truncate_trip --trip T2 --to "14 St" # short-turn / termina cedo
gtfs-tools split_trip --trip T2 --gap-from "Crescent St" --gap-to "Broadway Junction" --new-trip-id T2_SEC2 # divisão em duas seções
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=adicionar, 2=remover serviço na data
gtfs-tools delete_cal
…
[truncado para tradução]