Package Exports

trein
trein/dist/index.mjs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (trein) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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