choo

UK train times from your terminal.

choo to go to work. choo choo to come home.

Install

uvx choo

Or install permanently:

pip install choo

Quick start

# 1. Get API credentials
choo auth

# 2. Set up your commute
choo config alias.home "Highbury & Islington"
choo config alias.work "London Bridge"

# 3. Go
choo              # next trains home → work
choo choo         # reverse: work → home
choo "kings cross" york     # fuzzy station names work too

Commands

choo / choo next [FROM] [TO]

Show next trains between two stations. Defaults to home → work aliases.

choo                                 # home → work, now
choo --on tomorrow                   # home → work, tomorrow
choo paddington bristol              # fuzzy station names
choo next paddington bristol --at 08:30   # departing around 08:30
choo next KGX YRK --on monday        # CRS codes work too
choo next KGX YRK --count 10         # show 10 results

No trains running? Choo automatically shows tomorrow's first services.

choo choo

Reverse commute — next trains from work → home.

choo choo                            # heading home
choo choo --on friday                # Friday evening trains
choo choo board                      # departure board from work

choo board [FROM] [TO]

Departure board for a station. Same arguments as next, but shows all services in a table.

choo board "kings cross"             # all departures from King's Cross
choo board "kings cross" york        # filtered to York
choo board KGX --arrivals            # arrivals instead
choo board --on tomorrow             # defaults to home station

choo service UID

Full calling pattern for a service. Get the UID from board output.

choo service C41053
choo service C41053 --on 2026-03-16

choo config

Get/set configuration, like git config.

choo config alias.home "Highbury & Islington"   # set station alias
choo config alias.work "London Bridge"
choo config next.count 10                       # default number of results
choo config alias.home                          # get a value
choo config                                     # list all
choo config --unset alias.home                  # remove

choo auth

Guided setup for RTT API credentials. Walks you through registration at api-portal.rtt.io and verifies your credentials.

choo stations update

Fetch the latest station data from GitHub (2,599 UK stations).

Flags

Station resolution

Stations can be specified as:

• CRS codes: KGX, PAD, BRI (3 uppercase letters)
• Aliases: home, work (see choo config)
• Fuzzy names: "kings cross", paddington — matched against 2,599 stations with suggestions for ambiguous input

Configuration

Config file: ~/.config/choo/config.json (XDG via platformdirs)

Environment variables (override config):

traintimes SDK

Choo is built on the traintimes Python SDK, which wraps the RealTimeTrains Pull API.

from traintimes.sdk import Location, Service

# Departures from Highbury & Islington
response = Location("HIB").get()
for svc in response.services:
    print(svc.service_uid, svc.location_detail.gbtt_booked_departure)

# Full calling pattern for a service
service = Service("C41053", datetime.date.today()).get()
for loc in service.locations:
    print(loc.description, loc.gbtt_booked_departure)

The SDK provides Pydantic models for all API responses — see traintimes/models.py.

Credits

• Train data from the RealTimeTrains API
• Station data from davwheat/uk-railway-stations, licensed under the Open Database License (ODbL)