Rail CLI

UK National Rail CLI — live departures, arrivals, station search, destination filtering, batch station search from stdin, and lightweight field selection for...

Security Scan

The skill's requirements and runtime instructions are consistent with a CLI wrapper for National Rail (Darwin) data; the only noteworthy risk is installing an npm package from the public registry (normal but verify the package/author before installing).

Purpose & Capability

Name/description, required binary ('rail'), and required env (DARWIN_ACCESS_TOKEN) match: the CLI queries National Rail Darwin for departures/arrivals and station search, so the token and binary are expected and proportionate.

Instruction Scope

SKILL.md instructs the agent to run the 'rail' CLI and use the Darwin token; it does not ask the agent to read unrelated files, secrets, or system state beyond recommending how to set the token. Behavior (JSON/text output, stdin modes) is narrowly scoped to the stated functionality.

Install Mechanism

Install is an npm package (@shan8851/rail-cli) that exposes the 'rail' binary. Using npm is an expected delivery mechanism for a CLI written in Node, but installing code from a public registry carries moderate risk—verify the package author, version, and contents before installing system-wide.

Credentials

Only DARWIN_ACCESS_TOKEN is required and is justified for departures/arrivals. The SKILL.md mentions an optional RAIL_API_URL override that is not listed as required in registry metadata (minor documentation inconsistency but not a security mismatch). No other unrelated credentials are requested.

Persistence & Privilege

The skill is not forced-always and does not request system-wide config changes or other skills' credentials. Default autonomous invocation is allowed (platform default) and is not combined with other concerning privileges.

Assessment

This skill appears to do what it says: run the 'rail' CLI and use your Darwin access token for live rail data. Before installing, verify the npm package and author (e.g., check the package page, readme, recent versions, and package contents) because npm packages run code on your machine. Keep the DARWIN_ACCESS_TOKEN private and only provide it to trusted packages; if you prefer, inspect the package source or run it in a sandbox/container before global install. The SKILL.md mentions an optional RAIL_API_URL (not flagged as required) — you can ignore that unless you need to point to a custom Huxley2 instance.

Use rail for UK National Rail data: live departures, arrivals, station search, destination filtering, and agent-friendly batch search.

Setup

• npm install -g @shan8851/rail-cli
• Get a free Darwin access token: https://realtime.nationalrail.co.uk/OpenLDBWSRegistration/Registration
• export DARWIN_ACCESS_TOKEN=your_token or add to .env
• Station search works without a token. Departures and arrivals require one.

Departures

• From a station: rail departures KGX
• By station name: rail departures "kings cross"
• Filter to destination: rail departures "edinburgh" --to "york"
• Include calling points: rail departures KGX --expand
• Limit results: rail departures KGX --limit 5

Arrivals

• At a station: rail arrivals "leeds"
• By CRS code: rail arrivals LDS
• Filter from origin: rail arrivals "leeds" --from "london"
• Include calling points: rail arrivals LDS --expand
• Limit results: rail arrivals LDS --limit 5

Station Search

• Search by name: rail search "waterloo"
• Return only CRS codes: rail search "waterloo" --select crs
• Return only names: rail search "waterloo" --select name
• Return explicit name + CRS projection: rail search "waterloo" --select name,crs
• Batch search from stdin: printf "waterloo\nvictoria\n" | rail search --stdin
• Batch search as JSON: printf "waterloo\nvictoria\n" | rail search --stdin --json

Output

• All commands default to text in TTY, JSON when piped
• Force JSON: rail departures KGX --json
• Force text: rail departures KGX --text
• Disable colour: rail --no-color departures KGX
• Success envelope: { ok, schemaVersion, command, requestedAt, data }
• Error envelope: { ok, schemaVersion, command, requestedAt, error }

Agent Notes

• rail search --stdin is pipeline-only and expects newline-delimited queries on stdin
• rail search --select is intentionally narrow: name, crs, or name,crs
• rail search --stdin and a positional query cannot be used together
• Search output stays stable unless projection flags are explicitly used
• Errors are structured and suitable for agent retry/self-correction

Configuration

• DARWIN_ACCESS_TOKEN — required for departures/arrivals (free registration)
• RAIL_API_URL — optional, override Huxley2 instance URL (default: public instance)

Notes

• Accepts station names ("kings cross", "leeds") and CRS codes (KGX, LDS, EDB)
• CRS codes are 3-letter station identifiers
• Covers every National Rail station in Great Britain
• Data powered by National Rail Darwin via Huxley2
• Exit codes: 0 success, 2 bad input or ambiguity, 3 upstream failure, 4 internal error
• When a station name is ambiguous, the error includes candidate suggestions