CliDeck
WORKSPACE

Logging a Serial Session on macOS: `screen -L`, Session Naming, and Best Practices

← Back to Blog

Logging a Serial Session on macOS: screen -L, Session Naming, and Best Practices

Meta description: A practical guide to logging serial console sessions on macOS using GNU screen: how to use -L, -Logfile, -S, -h, detached mode, safe reattach, and simple habits that prevent lost logs.

Why you should log serial sessions

If you work with serial consoles (network gear, embedded devices, UART debug), logs aren’t a “nice-to-have.” They help you:

  • capture boot output and critical errors,
  • keep an audit trail of what happened and when,
  • share exact output with a teammate,
  • compare “before vs after” changes.

screen on macOS is a common, fast tool—but people still lose logs due to a few predictable mistakes. The workflow below keeps things reliable.

If you run multiple sessions and want logs/history organized automatically (without managing files by hand), that’s exactly the kind of workflow CliDeck is built for: CliDeck Workspace.

The baseline command (works for most real setups)

Practical default: name the session + write logs to a known file

screen -S R1-9600 -L -Logfile "$HOME/serial-logs/R1-$(date +%F_%H-%M-%S).log" /dev/cu.usbserial-XXXX 9600

What this does:

  • -S R1-9600 gives the session a readable name
  • -L turns on logging
  • -Logfile ... sets the exact log path and filename (with a unique timestamp)
  • /dev/cu... 9600 connects to the serial port at the chosen speed

Important: on macOS, for interactive console work you almost always want /dev/cu.*, not /dev/tty.*.

One-time setup: create a dedicated log folder

mkdir -p "$HOME/serial-logs"

Now you always know where logs live, and you don’t end up hunting through random directories.

What -L, -S, -h, and “detached mode” actually do

-L — enable logging

When enabled, screen writes session output to a log file.

-Logfile <file> — set the log path and filename

Without this, screen may write a default log in your current directory (often not where you expect). With -Logfile, you control exactly where the log goes.

Example:

screen -L -Logfile "$HOME/serial-logs/session.log" /dev/cu.usbserial-XXXX 9600

-S <name> — name the session

This is critical when you have multiple devices.

Example:

screen -S SW1 -L -Logfile "$HOME/serial-logs/SW1.log" /dev/cu.usbserial-XXXX 9600

-h <lines> — scrollback buffer size

This is not disk logging. It controls how many lines you can scroll back inside screen.

Example (50,000 lines):

screen -h 50000 -S SW1 -L -Logfile "$HOME/serial-logs/SW1.log" /dev/cu.usbserial-XXXX 9600

Detached mode: keep sessions (and logs) alive

Start a session detached (in the background) with logging

If you want the session to keep running even if you close your terminal window:

screen -dmS SW1 -L -Logfile "$HOME/serial-logs/SW1-$(date +%F_%H-%M-%S).log" /dev/cu.usbserial-XXXX 9600
  • -d -m (commonly written as -dmS) starts the session detached
  • logging continues even when you are not attached

List sessions (don’t forget the dash)

A very common mistake is typing screen ls (no dash). Correct is:

screen -ls

Reattach by name

screen -r SW1

If the session is “Attached” somewhere else

screen -d -r SW1

This detaches the other client and attaches you.

How not to lose log files

Rule #1: always use -Logfile with an absolute path

That prevents logs from “ending up somewhere random.”

Recommended pattern:

-Logfile "$HOME/serial-logs/<device>-<timestamp>.log"

Rule #2: make filenames unique (timestamps)

If you always write to the same file, you’ll mix sessions or overwrite content.

Good pattern:

"DEVICE-$(date +%F_%H-%M-%S).log"

Rule #3: encode device context in the session name (-S)

When you have 3–5 active sessions, default names are not helpful.

Good examples:

  • R1-9600
  • SW1-console
  • FW-USB-A

Best practices for reliable serial logging

1) Record basic context at the start

It’s very useful to have a small “header” with port, speed, and timestamp.

A simple approach is to prepend a line into the log file:

printf "Device=SW1 Port=/dev/cu.usbserial-XXXX Speed=9600 Started=%s\n\n" "$(date)" >> "$HOME/serial-logs/SW1-$(date +%F).log"

2) For console work, keep flow control off

Not a screen feature, but a frequent cause of odd behavior. For most console sessions, flow control should be disabled unless you explicitly need it.

3) Don’t dump logs into Desktop/Downloads

Keep a dedicated folder, so logs are easy to find and archive.

4) If logs matter, start detached

Detached sessions don’t die when your terminal window closes.

5) Don’t confuse scrollback with logging

-h improves scrollback; it does not guarantee the output is saved. For saving, you need -L and a real -Logfile.

Command cheat sheet

GoalCommand
Start a named session with loggingscreen -S SW1 -L -Logfile "$HOME/serial-logs/SW1-$(date +%F_%H-%M-%S).log" /dev/cu.usbserial-XXXX 9600
Start detached with loggingscreen -dmS SW1 -L -Logfile "$HOME/serial-logs/SW1-$(date +%F_%H-%M-%S).log" /dev/cu.usbserial-XXXX 9600
List sessionsscreen -ls
Reattachscreen -r SW1
Take over an attached sessionscreen -d -r SW1

Where CliDeck can be easier (practical, not salesy)

screen is a great built-in tool: fast, local, and offline. But when you have:

  • multiple devices,
  • a need for clean log archives,
  • frequent sharing and reviewing of history,
  • browser-first access to sessions,

it’s easier to use a workspace that treats sessions and logs as first-class features. That’s exactly what we’re building with CliDeck: CliDeck Features and CliDeck Workspace.

Bottom line

If you want to stop losing logs with screen on macOS, use this pattern:

  • always name sessions: -S
  • enable logging: -L
  • always set a known path and a unique filename: -Logfile "$HOME/serial-logs/<name>-<timestamp>.log"
  • increase scrollback if needed: -h
  • run important sessions detached: -dmS

This turns screen into a reliable serial logging setup you can repeat every time.