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 or UDP stream, import a PCAP file, export packets, and change common settings. Version 1.18.0 adds workspace tabs, Split View controls, Overview and endpoint statistics, and commands that target a specific tab or pane.

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 TCP, UDP, and DNS conversations as text, hex, or base64.
• Manage tabs, Split View, and each pane's source and display filters.
• Read Overview and endpoint statistics without opening their views.
• 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. Creating additional tabs and opening a second split pane require PRO, just as they do in the app.

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

4. Read the main help page:

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

5. 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.
• Commands use the current selection unless you supply a workspace, tab, or pane ID.

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.

Queries default to --scope all. Add --scope displayed and --pane-id to use that pane's current source and display filters. Queries do not change the app's filters; use pane update when you want to change the visible packet list.

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

Read the TCP or UDP stream that contains one packet. Choose both directions or one direction, then choose text, hex, or base64 output. --protocol auto is the default; use --protocol tcp or --protocol udp to specify the transport. DNS follows its underlying TCP or UDP stream.

"/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

Stream follow scans at most 250,000 candidate packets and returns at most 4 MiB or 10,000 records. Add --tab-id or --pane-id to follow a conversation in a specific capture.

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 into a new offline tab.

"/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, without other files in the same command.

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

Imports select the new tab by default. Use --select false to leave the current tab selected. To replace a tab, supply its ID and --yes:

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" file import "/Users/me/Desktop/replacement.pcapng" --tab-id "$TAB_ID" --yes

Replacement preserves selection unless you also pass --select true. The response includes the imported tab's ID. Replace $TAB_ID with a value from tabs list.

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 current capture source as a TCP Viewer session. Add --tab-id or --pane-id to choose another target.

"/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. Workspaces, tabs, and Split View

Start by discovering workspace, tab, and pane IDs:

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

Use --workspace-id, --tab-id, and --pane-id to target a specific window, tab, or pane. IDs are valid until their object closes. Replacing an imported tab keeps its tab ID but creates new pane IDs. Invalid IDs return an error.

In the examples below, set $WORKSPACE_ID, $TAB_ID, and $PANE_ID to IDs returned by discovery commands.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" tabs create --workspace-id "$WORKSPACE_ID"
"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" tabs select --tab-id "$TAB_ID"
"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" tabs move 0 --tab-id "$TAB_ID"
"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" split set on --tab-id "$TAB_ID"
"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" tabs list --workspace-id "$WORKSPACE_ID" --pretty

tabs create leaves the new tab unselected unless you add --select. Live tabs share the workspace capture. tabs move uses a zero-based index. After opening Split View, call tabs list again to discover the second pane.

Read its settings, list source IDs, and set a DNS filter:

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" pane get --pane-id "$PANE_ID"
"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" sources list --pane-id "$PANE_ID" --limit 50
"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" pane update --pane-id "$PANE_ID" --quick-filter dns --mode packets
"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" packets list --pane-id "$PANE_ID" --scope displayed --limit 20

pane update preserves omitted fields and waits for filters to apply. It supports these options:

Option	Purpose
--mode packets|overview	Choose the pane's view.
--source-id ID	Select an exact source ID from sources list.
--display-filter TEXT	Set a text filter. Pass an empty string to clear it.
--wireshark-filter EXPRESSION	Set a Wireshark display filter. Pass an empty string to clear it.
--structured-filter-json JSON	Set a structured filter group in the same format as MCP's structured_filter.
--quick-filter ID	Add protocol filters to this update. Repeat for several IDs.
--clear-quick-filters	Clear protocol quick filters.
--packet-id ID or --clear-packet	Select or deselect a packet.
--endpoint-group GROUP --endpoint-key KEY or --clear-endpoint	Apply or clear a statistics row's endpoint filter.

Quick-filter IDs are all, tcp, udp, dns, http, tls, websocket, clientHello, serverHello, and errors. See TCP Viewer MCP for a structured-filter example.

Reads and updates preserve the selected tab and focused pane. Use tabs select or pane focus to change them. These commands do not bring the app to the front.

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" pane focus --pane-id "$PANE_ID"
"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" split set off --tab-id "$TAB_ID"

Close a tab with tabs close --tab-id "$TAB_ID" --yes. Closing the last tab stops capture and closes its window.

12. Overview and endpoint statistics

Read the complete source's Overview without opening its view:

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" overview get --tab-id "$TAB_ID" --pretty

Overview includes totals, time range, protocols, top apps and destinations, and a timeline. It always uses the full source.

Query endpoint statistics for the complete capture or a pane's displayed packets:

"/Applications/TCP Viewer.app/Contents/MacOS/tcpviewer-cli" statistics endpoints --pane-id "$PANE_ID" --scope displayed --group udp --sort bytes --order desc --limit 50 --pretty

Groups are apps, domains, ipv4, ipv6, tcp, and udp. The defaults are Apps, all packets, bytes descending, and 50 rows. Use --search to filter rows and --offset with the returned next_offset to continue. A page can contain up to 500 rows.

Sort columns are address, port, protocol, client, domain, packets, bytes, tx_packets, tx_bytes, rx_packets, rx_bytes, and summary. Use the group and key in a row's endpoint object with pane update to show related packets.

Analysis uses a fixed capture watermark. captured_through_packet_id and source_packet_count describe the analyzed snapshot; new packets do not extend that request. One analysis runs per capture source at a time. Closing or replacing the source cancels its analysis.

13. 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. Overview, endpoint statistics, pane reads and updates, and source lists wait up to 120 seconds; analysis itself has a 100-second deadline. Import, export, and stream 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.

14. Related pages

• Tab mode
• Split View
• Capture overview
• Endpoints
• Live packet capture
• Filter packets
• Follow TCP and UDP streams
• Open capture files
• Save, copy, and export
• TCP Viewer MCP