NSLogger CLI Harness — SOP

What is NSLogger

NSLogger is a macOS application for receiving, viewing, and analyzing log messages sent by iOS/macOS applications using the NSLogger client library.

Core Concepts

Concept	Description
`.nsloggerdata`	Saved binary-plist session file (opened/exported by the GUI)
`.rawnsloggerdata`	Raw wire-protocol capture file
Message	A single log entry with: sequence, timestamp, level, tag, threadID, type, text
Message Types	`text`, `image`, `data`
Log Level	0=error, 1=warning, 2=info, 3=debug, 4=verbose (higher=noisier)
Connection	A live client connection (by Bonjour or direct TCP on port 50000)
Filter	A predicate that restricts which messages are displayed

Wire Protocol (rawnsloggerdata)

NSLogger uses a custom binary protocol over TCP:

[4-byte big-endian total message length]
[4-byte big-endian sequence number]
[2-byte part count]
for each part:
    [1-byte part key]
    [1-byte part type]
    [4-byte big-endian data length]
    [N bytes data]

Part keys: 0=messageType, 1=timestamp_s, 2=timestamp_ms, 3=timestamp_us, 4=threadID, 5=tag, 6=level, 7=message, 8=imageWidth, 9=imageHeight, 10=messageSeq, 11=filename, 12=lineNumber, 13=functionName, 20=clientName, 21=clientVersion, 22=osName, 23=osVersion, 24=clientModel, 25=uniqueID

Part types: 0=string(UTF8), 1=binary, 2=int16, 3=int32, 4=int64, 5=image

Message types: 0=log, 1=blockStart, 2=blockEnd, 3=clientInfo, 4=disconnect, 255=marker

CLI Command Groups

cli-anything-nslogger read     # Parse and display .nsloggerdata / .rawnsloggerdata
cli-anything-nslogger filter   # Filter messages from a file (level, tag, thread, text, regex, type, time, seq)
cli-anything-nslogger export   # Export messages to text/JSON/CSV
cli-anything-nslogger stats    # Summary statistics for a file
cli-anything-nslogger listen   # Listen for live NSLogger connections
cli-anything-nslogger generate # Generate sample .rawnsloggerdata for testing
cli-anything-nslogger tail     # Show last N messages from a file
cli-anything-nslogger clients  # List all client_info records in a file
cli-anything-nslogger blocks   # Show block start/end structure as indented tree
cli-anything-nslogger merge    # Merge multiple files sorted by timestamp

Typical Agent Workflow

# Inspect a captured log file
cli-anything-nslogger read session.rawnsloggerdata

# Find all errors
cli-anything-nslogger filter --level 0 session.rawnsloggerdata

# Filter within a time window
cli-anything-nslogger filter --after "10:30:00" --before "10:45:00" session.rawnsloggerdata

# Filter by sequence range
cli-anything-nslogger filter --from-seq 100 --to-seq 200 session.rawnsloggerdata

# Show last 50 messages
cli-anything-nslogger tail --count 50 session.rawnsloggerdata

# List connected clients
cli-anything-nslogger clients session.rawnsloggerdata

# Show block/call structure
cli-anything-nslogger blocks session.rawnsloggerdata

# Merge two capture files
cli-anything-nslogger merge a.rawnsloggerdata b.rawnsloggerdata --format json

# Export for further analysis
cli-anything-nslogger export --format json session.rawnsloggerdata > logs.json

# Get statistics
cli-anything-nslogger stats session.rawnsloggerdata

# Listen for live iOS logs via Bonjour, matching NSLogger.app
cli-anything-nslogger listen --bonjour --name bazinga --debug

# Mirror live logs to disk while still printing stdout
cli-anything-nslogger listen --bonjour --name bazinga --output app.log

# Direct TCP/TLS mode for manually configured clients
cli-anything-nslogger listen --port 50000 --ssl --debug

3.7 KiB Raw Blame History