serterm

README

SerTerm

A simple serial terminal for the command line. With AI agent-friendly CLI commands, talk to anything that speaks serial.

Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/eliachiarucci/serterm/main/install.sh | sh

Windows

Download the zip for your architecture from the latest release, extract serterm.exe, and put it on your PATH.

Packages

.deb, .rpm, and .apk packages are attached to each release.

Or build from source (see Build below).

Usage

serterm

Running serterm with no arguments starts the interactive device picker. There are also a few subcommands:

Command	Action
serterm list	list connected serial devices (device, tab, description)
serterm open [--baud N] <device>	connect and go straight to the terminal screen
serterm open [--baud N] <device> <secs>	stream logs to stdout for secs seconds (max 60), then exit
serterm open --send "text" <device> <secs>	send a line to the device, then stream the response
serterm update	update serterm to the latest release (runs the install script)
serterm help	show usage

The timed form of open is designed for scripts and AI agents: it needs no TTY, prints raw device output, and always releases the port when it exits. Without a time limit, open refuses to run if stdout is not a terminal.

serterm open --baud 9600 /dev/cu.usbmodem1101 5   # capture 5 seconds of logs
serterm open --send "status" /dev/cu.usbmodem1101 3   # send a command, capture the reply

serterm --version prints the version.

Device picker

Key	Action
↑/↓	select device
←/→	change baud rate (default 115200)
enter	connect
r	refresh device list
q	quit

Terminal

Key	Action
enter	send the input line (a \n is appended)
ctrl+l	clear the output stream
ctrl+d	back to the device picker
pgup/pgdn	scroll the output
ctrl+c	quit

The output also scrolls with the mouse wheel (via the emulator's alternate scroll mode). serterm never captures the mouse, so your terminal's native text selection and copy shortcuts work as usual.

Sent messages are echoed in the stream prefixed with →. If the device is unplugged, a notice appears and ctrl+d returns to the picker.

Build

go build -ldflags="-s -w" -o serterm .

Produces a single self-contained binary, no runtime dependencies.

Test

go test ./...

Code layout

• main.go — root model; switches between the two screens
• cli.go — list, open, update, and help subcommands
• ports.go — device discovery (hides macOS /dev/tty.* duplicates, USB first)
• picker.go — device selection screen
• terminal.go — streaming view, input line, serial reader goroutine
• styles.go — shared lipgloss styles

License

MIT

Documentation

Overview

SerTerm is a small serial terminal for the command line.

It shows a list of serial devices to pick from, then streams the device's output while a reserved bottom line accepts messages to send. Ctrl+D returns to the device list, Ctrl+C quits.