Skip to main content

TCP Viewer Command Line

tcpviewer-cli lets you control TCP Viewer from Terminal, a script, or another app. It can start a capture, find packets, inspect a TCP stream, import a PCAP file, export packets, and change common settings.

The command is included inside TCP Viewer. You do not need to install a second tool.

1. What you can do​

  • Check whether TCP Viewer is running.
  • List network interfaces and control a live capture.
  • Find packets with simple or advanced filters.
  • Read decoded packet fields and raw bytes.
  • Follow a TCP stream as text, hex, or base64.
  • Import PCAP, PCAPNG, and TCP Viewer session files.
  • Export selected packets or a complete session.
  • Check, activate, or revoke a license.
  • Read and change common app settings.
  • Get stable JSON output for scripts and other apps.

Normal command-line operations do not require TCP Viewer PRO.

2. How to use the command line​

  1. Install TCP Viewer in the /Applications folder.
  2. Open Terminal.
  3. Check that the bundled command is available:
"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" --version
  1. Read the main help page:
"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" --help
  1. Add --help after a command to see its options:
"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" capture start --help

The examples on this page always use the full path to tcpviewer-cli. They work with the normal TCP Viewer installation in /Applications.

Most commands return JSON. Add --output text when you want a result that is easier to read in Terminal:

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" app status --output text

If TCP Viewer is closed, most commands launch it without bringing it to the front. The app stays open after the command finishes.

  • app status checks the closed state without launching the app.
  • packets reveal brings TCP Viewer to the front so you can see the packet.
  • Other commands use the main or most recently used TCP Viewer window.

3. App and interface commands​

app status​

Check the app version, running state, license state, active file, capture state, and packet count.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" app status --pretty

interfaces list​

List capture interfaces, addresses, capabilities, and the current selection. Use the returned interface ID with capture start.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" interfaces list --pretty

4. Capture commands​

capture status​

Check whether the active capture is ready, running, paused, or stopped.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" capture status

capture start​

Start a new capture on an interface. Starting a capture clears packets from the active workspace.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" capture start --interface en0

Add a BPF filter only when you want to limit future packets. Packets that do not match the filter are not captured.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" capture start --interface en0 --bpf 'tcp port 443'

capture pause​

Pause a running capture without deleting its packets.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" capture pause

capture resume​

Continue a paused capture.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" capture resume

capture stop​

Stop the active capture.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" capture stop

5. Packet commands​

Packet IDs are decimal values returned by packets list. Packet commands use recent packets first unless you add --order oldest.

packets list​

List matching packets with a result limit.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" packets list --protocol DNS --limit 25 --pretty

packets summary​

Summarize matching protocols, domains, clients, bytes, and time ranges.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" packets summary --domain example.com --scan-limit 50000 --pretty

packets details​

Read the decoded protocol tree for one packet.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" packets details 120 --max-depth 12 --max-nodes 5000 --pretty

packets bytes​

Read a limited range of raw bytes. Output is base64 by default. This example returns 256 bytes as hex.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" packets bytes 120 --offset 0 --length 256 --encoding hex

packets clear​

Remove every packet from the active workspace. The --yes option is required.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" packets clear --yes

packets reveal​

Select a packet in TCP Viewer, open its inspector, and bring the app to the front.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" packets reveal 120

6. Packet filters​

Use these options with packets list, packets summary, stream packets, and filtered file export commands:

  • --protocol DNS
  • --domain example.com
  • --address 192.168.1.20
  • --port 443
  • --client Safari
  • --packet-id 120
  • --stream-id 7
  • --filter field:operator:value

Repeat an option to match more than one value. This example finds DNS or TLS packets from Safari:

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" packets list --protocol DNS --protocol TLS --client Safari --limit 100

Advanced filters support up to 20 rules. Use --match and when every advanced rule must match, or --match or when any rule may match:

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" packets list --filter 'source_port:equals:443' --filter 'length:greater_than:500' --match and --limit 50

IPv6 values work because the CLI splits only the first two colons:

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" packets list --filter 'source_address:equals:2001:db8::1' --limit 25

Common advanced fields include protocol, domain, source_address, destination_address, source_port, destination_port, client, bundle_id, direction, stream_id, length, tcp_flags, and text.

Common operators include equals, not_equals, contains, not_contains, starts_with, ends_with, greater_than, less_than, and exists.

Use these options for large captures:

  • --limit returns 1 to 500 matching packets. The default is 50.
  • --scan-limit scans up to 100,000 packets. The default is 50,000.
  • --offset continues from next_offset.
  • --scan-offset continues from next_scan_offset.
  • --order oldest reads the oldest packets first.

7. Stream commands​

stream packets​

List packets in one TCP or UDP stream. Use a stream ID from packet output.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" stream packets 7 --limit 100 --pretty

stream follow​

Rebuild the TCP stream that contains one packet. Choose both directions or one direction, then choose text, hex, or base64 output.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" stream follow 120 --direction both --encoding text --max-bytes 4194304 --max-records 10000 --pretty

Direction values are:

  • both
  • client-to-server
  • server-to-client

TCP follow returns at most 4 MiB or 10,000 records.

8. File commands​

Use absolute file paths in scripts so the destination does not depend on the current Terminal folder.

file import​

Import one or more PCAP or PCAPNG files.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" file import "/Users/me/Desktop/first.pcap" "/Users/me/Desktop/second.pcapng"

Import a TCP Viewer session by itself. It replaces the current workspace.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" file import "/Users/me/Desktop/review.tcpviewsession"

file export​

Export all packets from the bounded scan:

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" file export "/Users/me/Desktop/all-traffic.pcapng" --format pcapng --all

Or export packets that match at least one selector:

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" file export "/Users/me/Desktop/dns.pcap" --format pcap --protocol DNS --limit 500

The CLI does not replace an existing file unless you add --overwrite. It also refuses to write through a symbolic link.

file export-session​

Export the active workspace as a TCP Viewer session.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" file export-session "/Users/me/Desktop/review.tcpviewsession"

9. License commands​

The CLI never returns your license key or receipt signature.

license status​

Check the current license state.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" license status --pretty

license activate​

Run the command and enter the key at the hidden prompt:

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" license activate

For a script, store the key outside the script and pass it through stdin:

printf '%s\n' "$TCPVIEWER_LICENSE_KEY" | "/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" license activate

Do not put a license key in a command argument, log, or committed file.

license revoke​

Revoke this Mac's license seat. The --yes option is required.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" license revoke --yes

10. Settings commands​

Supported setting keys are:

  • theme: system, light, or dark
  • packet_font_size: 10 through 24
  • monospaced_font: a Boolean value
  • analytics: a Boolean value
  • crash_reports: a Boolean value
  • quit_confirmation: a Boolean value
  • mcp_enabled: a Boolean value
  • mcp_redaction: a Boolean value

Boolean values can be true or false, yes or no, on or off, or 1 or 0.

settings list​

List every supported setting and its current value.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" settings list --pretty

settings get​

Read one setting.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" settings get theme

settings set​

Change one setting.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" settings set theme dark

settings reset​

Reset one setting to its default value:

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" settings reset theme

Reset every supported setting. The --yes option is required:

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" settings reset --all --yes

11. Output, timeouts, and exit codes​

Every command supports these options:

  • --output json returns JSON. This is the default.
  • --output text returns readable text.
  • --pretty formats JSON with indentation.
  • --timeout SECONDS changes how long the CLI waits for the app.

Normal commands wait up to 30 seconds. License commands wait up to 60 seconds. Import, export, and TCP follow commands wait up to 300 seconds. A long app operation may finish after the CLI times out.

Exit codes are:

  • 0: success
  • 2: invalid command or argument
  • 3: app launch, communication, or timeout error
  • 4: TCP Viewer could not complete the command

Success JSON is written to standard output. Error JSON is written to standard error. Responses include a schema version, request ID, command name, result, and error details when a command fails.