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

1. Always use --json when parsing output programmatically
2. Station names are flexible - accepts partial matches, quotes for multi-word
3. Time format - HH:MM (24-hour), date format YYYY-MM-DD
4. 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