NMEA 2000 for Humans and Agents

Decode, record, replay, validate, filter, and discover devices - all from a nicely packaged TUI.

Powered by the open-ships/n2k Go library.

Installation

curl -fsSL https://raw.githubusercontent.com/open-ships/n2k-cli/main/install.sh | sh

Homebrew

On macOS or Linux:

brew install --cask open-ships/tap/n2k
n2k version

Homebrew upgrades are also available directly:

brew upgrade --cask open-ships/tap/n2k

Why n2k?

One tool for the whole debugging loop

Use Case	Why use n2k cli
Inspect traffic now	Decode SocketCAN, USB-CAN, TCP, UDP, candump, and gzip captures.
Reproduce a problem	Record owned observations, replay with original or disabled timing.
Reduce the firehose	Filter messages using Common Expression Language and select typed, text, JSON, or unknown-PGN output.
Find devices	Actively discover a writable network or passively inventory a saved capture.
Measure decoder coverage	Validate a source, count undecodable PGNs, and fail CI in strict mode.
Understand a PGN	Autocomplete every known PGN and inspect fields, units, ranges, and confidence.

Rich terminal workflows

Interactive command center

Launch the TUI:

n2k

The command center provides:

• Fuzzy command search with /, keyboard navigation, and 1–7 shortcuts.
• Guided source selection for SocketCAN, USB-CAN, TCP/UDP gateways, and files.
• Inline validation for paths, durations, addresses, formats, and PGNs.
• Tab-completable capture paths, common interfaces, gateway addresses, CEL filters, durations, and every known PGN number.
• A reviewable, copyable command preview before anything runs.
• Terminal-aware colors, contextual key help, cancellation, and a full-screen alternate buffer that leaves the shell clean.

Scriptable commands

The same workflows retain deterministic stdout and exit behavior:

# Yacht Devices WiFi gateway (RAW server mode) -- decoded JSON in one command
n2k sniff --tcp 192.168.4.1:1457

# Concrete Go PGN types with scaled physical values and SI units
n2k sniff --file capture.log --output text

# SocketCAN (Linux), USB-CAN serial, UDP, or capture replay
n2k sniff -i can0
n2k sniff -u /dev/ttyUSB0
n2k sniff --udp :1457
n2k sniff --file capture.log            # add --timing to replay at real speed
n2k sniff --file capture.log.gz         # gzip captures are expanded automatically

# CEL filtering, unknown PGNs, jq-friendly output
n2k sniff -i can0 -f 'pgn == 127250' --unknown | jq .

# Record, replay, validate, discover, and inspect schema support
n2k record -i can0 --out capture.log
n2k record --tcp 192.168.4.1:1457 --out observations.jsonl --output-format jsonl
n2k replay --timing=false capture.log
n2k validate --file capture.log --strict
n2k devices --tcp 192.168.4.1:1457 --wait 5s
n2k devices --file capture.log.gz
n2k devices list --file capture.log.gz  # "list" is an optional, readable alias
n2k pgn 127250
n2k pgn list | jq 'select(.complete == true)'

Command	Functionality
n2k / n2k tui	Open the searchable command palette and guided workflow forms.
n2k sniff	Decode live or recorded traffic into typed JSON lines or concrete PGN text with physical values.
n2k record	Capture replayable candump or owned observation JSON lines.
n2k replay	Replay and decode a candump capture, optionally preserving its original timing.
n2k validate	Count typed and undecodable messages by PGN and optionally fail in strict mode.
n2k devices	Actively discover a writable bus or passively inventory devices observed in a capture/UDP stream.
n2k pgn	Query or list typed PGN metadata, fields, ranges, and confidence.
n2k update	Check for a release and update through Homebrew, Go, or a verified release binary.
n2k uninstall	Remove n2k and its update-check cache from the machine.

Run n2k help <command> for organized flags, defaults, allowed values, and examples. The purpose-built parser enforces canonical --long-flags, supports --flag=value, validates choices before starting I/O, and suggests the nearest command or flag after a typo.

devices accepts the same source vocabulary as the other inspection commands. SocketCAN, USB, and TCP sources perform active discovery; files are scanned to completion; UDP is observed for --wait. Both n2k devices --file … and the more conversational n2k devices list --file … are valid. Capture files may be plain candump text or gzip-compressed.

Updates

Check for and install the latest release:

n2k update

Useful controls:

n2k update --check             # report only; do not install
n2k update --force             # reinstall the latest release
n2k update --method homebrew   # override: homebrew, go, or binary

The interactive command center checks for updates at most once every 24 hours and offers to install them before opening. Set N2K_AUTO_UPDATE=1 to install without the confirmation prompt, or N2K_NO_UPDATE_CHECK=1 to disable the automatic check. Scriptable commands never perform implicit network requests or updates.

Uninstall

Remove n2k and its update-check cache:

n2k uninstall

Shell completion

Enable completion for the current shell with one of:

source <(n2k completion bash)                              # Bash
source <(n2k completion zsh)                               # Zsh
n2k completion fish | source                              # Fish
n2k completion powershell | Out-String | Invoke-Expression # PowerShell

Completion is dynamic rather than a static command list. It understands:

• Commands and unused flags, with descriptions.
• Source and output paths, including directory traversal.
• Stream, message, and capture formats.
• SocketCAN interface names, common gateway addresses, and Go durations.
• CEL filter examples.
• Every known PGN number with its description.

Output

sniff and replay default to JSON lines containing typed structs and their exact wire values. The demo projects the metadata envelope down to its PGN for readability. Set --output text for the concrete pgn.<Type>, source address, scaled physical values, SI units, and lookup type names.

record writes replayable candump by default. JSON-lines mode retains each owned source observation, including adapter and network identity, source and receipt timestamps, gateway-relative time, direction, and frame bytes. The Go library's observation stream additionally exposes assembled messages and decode errors.

Development

Go 1.26.5 or newer and just are required.

just setup # first checkout only
just test
just lint
just secure

Releases follow semantic versioning. VERSION declares the release baseline, and fully green release automation publishes the tag and prebuilt binaries.

License

MIT — see LICENSE.