CLI Reference

The SerialFlow CLI connects local serial devices to SerialFlow from your terminal.

Installation

macOS:

brew install nirosoftware/serialflow/serialflow

Linux:

curl -fsSL https://github.com/Nirosoftware/serialflow-releases/releases/latest/download/serialflow-linux-x64 -o serialflow
chmod +x serialflow
sudo install -m 0755 serialflow /usr/local/bin/serialflow

On Linux ARM64, replace serialflow-linux-x64 with serialflow-linux-arm64.

Windows:

winget install --id Nirosoftware.SerialFlow --exact --source winget

Then verify the install:

serialflow --version

Upgrade later on Windows with:

winget upgrade --id Nirosoftware.SerialFlow --exact

For platform-specific installation steps, see CLI Installation.

Authentication

serialflow auth login

Sign in from your terminal (OAuth device flow):

serialflow auth login

On success, the CLI opens a browser, asks you to confirm the device code, stores the resulting token in the OS keychain, and prints Logged in..

Options:

Option Description
--scope <scope> Request a specific OAuth scope

serialflow auth status

Show whether the CLI currently has a stored login token:

serialflow auth status

Use --json for machine-readable output:

serialflow auth status --json

serialflow auth logout

Revoke the current CLI session token when possible, then clear the stored keychain token:

serialflow auth logout

Device Discovery

serialflow device list

List serial ports visible on the local machine:

serialflow device list

Use --json to print a JSON array instead of text:

serialflow device list --json

The text output looks like this:

Available serial ports:
  /dev/tty.usbserial-1234  (USB FTDI, vid:0x0403 pid:0x6001)

Device Connection

serialflow device connect <path>

Connect a local serial port and register it with SerialFlow:

serialflow device connect /dev/ttyUSB0

Set the baud rate and device name explicitly:

serialflow device connect /dev/ttyUSB0 --baud 115200 --name 'Lab ESP32'

Supported options:

Option Description
--baud <baud> Serial baud rate. Default: 115200
--name <name> Name to register for the connected device
--token <token> Use an explicit CLI token instead of the stored keychain token
--timeout <seconds> Connection timeout in seconds. Default: 10
--heartbeat-interval <seconds> Heartbeat interval in seconds. Default: 15
--serial-read-timeout-ms <ms> Serial read timeout in milliseconds. Default: 20

If --token is omitted, the CLI uses the token stored by serialflow auth login.

Piping Data From Stdin

serialflow pipe

Stream newline-delimited data from stdin into a Studio graph:

some-command | serialflow pipe --name "my stream"

For example, follow a log file:

tail -f /var/log/system.log | serialflow pipe --name "system log"

serialflow pipe registers a receive-only stream on your account. In Studio, drop a Remote source node into your graph: if Studio can match the stream to exactly one Remote source node, it connects them automatically; otherwise pick the stream in the node’s settings.

By default the pipe does not consume stdin immediately. It waits (up to --wait-timeout, default 10 seconds) for Studio to attach the resource to a Remote source node, then for the flow to be ready (click Run Flow in Studio), and only then starts reading stdin. This way the beginning of your stream is not lost while you wire up the graph. Pass --no-wait (or --wait-timeout 0) to start streaming immediately instead.

Each line of stdin becomes one frame. Frames larger than --max-frame-bytes abort the pipe with an error suggesting you split the input or raise the limit.

Supported options:

Option Description
--token <token> Use an explicit CLI token instead of the stored keychain token
--name <name> Display name for the pipe resource in Studio. Default: stdin pipe
--api-url <url> API endpoint. Env: SERIALFLOW_API_URL. Default: https://api.serialflow.app
--timeout <seconds> Connection timeout in seconds. Default: 10
--heartbeat-interval <seconds> Heartbeat interval in seconds. Default: 15
--wait-timeout <seconds> Seconds to wait — first for Studio to attach the pipe, then for the flow to start (Run Flow) — before reading stdin. Default: 10
--no-wait Start reading stdin immediately, skipping both waits
--max-frame-bytes <bytes> Maximum stdin line/frame size in bytes. Env: SERIALFLOW_MAX_FRAME_BYTES. Default: 65536

If --token is omitted, the CLI uses the token stored by serialflow auth login.

Version

serialflow version

Print the CLI version:

serialflow version

The root command also supports serialflow --version.

Global Options

All commands support these global options:

Option Description
--log-level <level> Set log verbosity
-v, --verbose Shortcut for debug logging
-q, --quiet Reduce log noise
--log-file <path> Write logs to a file

See Also