irail-cli
CLI for Belgian railways (NMBS/SNCB) via iRail API. No authentication required.
Quick Start
# Station departures
irail liveboard Brugge
# Find connections
irail connections Brugge Leuven
# Check disruptions
irail disturbances
Authentication
None required. iRail API is public and free to use.
Core Rules
- Always use
--json when parsing output programmatically
- Station names are flexible - accepts partial matches, quotes for multi-word
- Time format - HH:MM (24-hour), date format YYYY-MM-DD
- Language options - nl, fr, en, de (default: nl)
Output Formats
| Flag |
Format |
Use case |
| (default) |
Table |
User-facing with colors |
--json |
JSON |
Agent parsing, scripting |
Colors indicate: red = delays, yellow = platform changes.
Workflows
Liveboard (Departures/Arrivals)
# Departures from station
irail liveboard Brugge
irail liveboard "Brussel-Centraal"
# Arrivals instead of departures
irail liveboard Brugge --arrivals
# Specific date/time
irail liveboard Brugge --time 09:00 --date 2025-02-15
# JSON for scripting
irail liveboard Brugge --json
# Different language
irail liveboard Brugge --lang en
Connections (Route Planning)
# Find routes
irail connections Brugge Leuven
# Specific departure time
irail connections Brugge Leuven --time 09:00
# Arrive by time (instead of depart at)
irail connections Brugge Leuven --time 14:00 --arrive-by
# More results
irail connections Brugge Leuven --results 10
# JSON for parsing
irail connections Brugge Leuven --json
Stations
# List all stations
irail stations
# Search stations
irail stations --search bruss
irail stations --search gent
# JSON for scripting
irail stations --json
Vehicle (Train Info)
# Show train information
irail vehicle IC1832
# Include all stops
irail vehicle IC1832 --stops
# JSON output
irail vehicle IC1832 --json
Composition (Train Cars)
# Show train composition (seats, amenities)
irail composition S51507
irail composition IC1832
# JSON for parsing
irail composition S51507 --json
Disturbances
# All current disruptions
irail disturbances
# Only planned works
irail disturbances --type planned
# Only unplanned disruptions
irail disturbances --type disturbance
# JSON for scripting
irail disturbances --json
Scripting Examples
# Get next train to destination
irail connections Brugge Leuven --json | jq -r '.[0].departure'
# Find station ID
irail stations --search "brussel" --json | jq -r '.[0].id'
# Check if delays exist on liveboard
irail liveboard Brugge --json | jq '[.[] | select(.delay > 0)] | length'
# Get platform for next departure
irail liveboard Brugge --json | jq -r '.[0].platform'
# List all disruptions
irail disturbances --json | jq -r '.[].title'
Environment Variables
| Variable |
Description |
IRAIL_LANG |
Default language (nl, fr, en, de) |
IRAIL_JSON |
Default to JSON output |
NO_COLOR |
Disable colored output |
Language Options
| Code |
Language |
nl |
Dutch (default) |
fr |
French |
en |
English |
de |
German |
irail liveboard Brugge --lang fr
irail connections Brugge Leuven --lang en
Command Reference
| Command |
Description |
liveboard |
Station departures/arrivals |
connections |
Route planning between stations |
stations |
List/search stations |
vehicle |
Train information and stops |
composition |
Train car composition |
disturbances |
Service disruptions |
completion |
Shell completions |
Common Patterns
Check if train is delayed
irail vehicle IC1832 --json | jq '.delay // 0'
Get connection with transfers
irail connections Brugge Leuven --json | jq '.[0].vias | length'
Find direct trains only
irail connections Brugge Leuven --json | jq '[.[] | select(.vias == null or (.vias | length) == 0)]'
Guidelines
- No authentication needed - API is public
- Be mindful of API usage in loops - add delays between requests
- Station names are case-insensitive and support partial matching
- Delay values are in seconds (divide by 60 for minutes)
Installation
brew install dedene/tap/irail
dvcrn