Trein

A CLI for the NS (Dutch Railways) API. Get real-time train departures, plan journeys, and check disruptions from your terminal.

Installation

npm (Recommended)

npm install -g trein

Binary Download

Download the latest binary for your platform from the releases page.

Build from Source

git clone https://github.com/Joehoel/trein.git
cd trein
bun install
bun run build:bin

This creates a trein binary in the project root.

Configuration

Trein requires an NS API key. Get your free key at: https://apiportal.ns.nl/

Option 1: Environment Variable

export NS_API_KEY="your-api-key"

Option 2: Config File

Create ~/.config/trein/config.json:

{
  "apiKey": "your-api-key"
}

Or create trein.config.ts in your project:

export default {
  apiKey: "your-api-key",
  defaultStation: "ASD",
  watch: {
    interval: 30,
  },
};

Commands

Departures

Get departures from a station.

trein departures <station>
trein d <station>              # shorthand

Options: | Flag | Alias | Description | |------|-------|-------------| | --json | | Output as JSON | | --watch | -w | Auto-refresh mode | | --type | -t | Filter by train type (IC, SPR, INT) | | --limit | -n | Number of departures (default: 10) |

Examples:

# Get departures from Amsterdam Centraal
trein departures "Amsterdam Centraal"
trein d ASD

# Filter intercity trains only
trein d Utrecht -t IC

# Watch mode with 5 departures
trein d Rotterdam -w -n 5

# JSON output for LLM consumption
trein d Schiphol --json

JSON Output:

trein d ASD --json

{
  "departures": [
    {
      "direction": "Rotterdam Centraal",
      "plannedTime": "14:23",
      "actualTime": "14:25",
      "delay": "+2",
      "platform": "5a",
      "trainType": "IC",
      "operator": "NS",
      "cancelled": false
    }
  ]
}

Stations

Search for stations by name or code.

trein stations <query>
trein s <query>              # shorthand

Options: | Flag | Description | |------|-------------| | --json | Output as JSON |

Examples:

# Search for stations
trein stations amsterdam
trein s schiphol

# JSON output
trein s utrecht --json

JSON Output:

trein s amsterdam --json

{
  "stations": [
    {
      "name": "Amsterdam Centraal",
      "code": "ASD"
    },
    {
      "name": "Amsterdam Amstel",
      "code": "ASA"
    }
  ]
}

Trip

Plan a journey from A to B.

trein trip <from> <to>
trein t <from> <to>          # shorthand

Options: | Flag | Description | |------|-------------| | --json | Output as JSON | | --via | Travel via a specific station |

Examples:

# Plan a trip
trein trip Amsterdam Rotterdam
trein t ASD RTD

# Trip via Utrecht
trein t Amsterdam Rotterdam --via Utrecht

# JSON output
trein t ASD RTD --json

JSON Output:

trein t ASD RTD --json

{
  "trips": [
    {
      "departure": "14:30",
      "arrival": "15:12",
      "duration": "42 min",
      "transfers": 0,
      "status": "ON_TIME",
      "legs": [
        {
          "from": "Amsterdam Centraal",
          "to": "Rotterdam Centraal",
          "departure": "14:30",
          "arrival": "15:12",
          "trainType": "IC",
          "platform": "4b"
        }
      ]
    }
  ]
}

Disruptions

Show current disruptions and maintenance.

trein disruptions

Options: | Flag | Alias | Description | |------|-------|-------------| | --json | | Output as JSON | | --active | -a | Show only active disruptions | | --type | -t | Filter: DISRUPTION, MAINTENANCE, CALAMITY |

Examples:

# Show all disruptions
trein disruptions

# Active disruptions only
trein disruptions -a

# Filter by type
trein disruptions -t MAINTENANCE

# JSON output
trein disruptions --json

JSON Output:

trein disruptions --json

{
  "disruptions": [
    {
      "title": "Defect aan de trein",
      "type": "DISRUPTION",
      "isActive": true,
      "start": "2026-01-25T10:00:00",
      "end": "2026-01-25T14:00:00",
      "trajectories": ["Amsterdam - Utrecht"]
    }
  ]
}

Alias

Manage station aliases for quick access.

trein alias                  # list aliases
trein alias list             # list aliases
trein alias set <name> <station>
trein alias rm <name>

Options: | Flag | Description | |------|-------------| | --json | Output as JSON |

Examples:

# Set aliases
trein alias set home "Amsterdam Centraal"
trein alias set work Utrecht

# Use aliases in commands
trein d home
trein t home work

# List all aliases
trein alias list

# Remove an alias
trein alias rm work

# JSON output
trein alias list --json

JSON Output:

trein alias list --json

{
  "home": "ASD",
  "work": "UT"
}

LLM Usage

All commands support --json for structured output. This makes Trein ideal for LLM tool use:

# Get data in JSON format
trein d Amsterdam --json
trein t Amsterdam Rotterdam --json
trein disruptions --json
trein s utrecht --json

Error responses are also JSON:

{
  "error": "Station not found: \"xyz\""
}

Station resolution:

• Full names: "Amsterdam Centraal"
• Station codes: ASD, RTD, UT
• Partial matches: amsterdam, schiphol
• Aliases: home, work (user-defined)

Troubleshooting

API Key Not Found

Error: NS API key not found. Set NS_API_KEY environment variable or add apiKey to trein.config.ts

Solution: Set your API key via environment variable or config file. Get a free key at https://apiportal.ns.nl/

Station Not Found

{ "error": "Station not found: \"xyz\"" }

Solution: Use trein stations <query> to search for the correct station name or code.

Multiple Stations Match

In interactive mode, you'll be prompted to select. In JSON mode, the best match is used automatically.

License

MIT - see LICENSE