cli-anything-nslogger

A complete CLI harness for NSLogger, the macOS log viewer for iOS/macOS apps.

Installation

cd nslogger/agent-harness
pip install -e .
# Verify
cli-anything-nslogger --help

Command Reference

generate — Create sample files for testing

cli-anything-nslogger generate sample.rawnsloggerdata --count 50

read — Display messages from a file

# All messages
cli-anything-nslogger read session.rawnsloggerdata

# Errors only (level 0)
cli-anything-nslogger read session.rawnsloggerdata --level 0

# Filter by tag and text search
cli-anything-nslogger read session.rawnsloggerdata --tag Network --search "timeout"

# First 20 messages as JSON
cli-anything-nslogger read session.rawnsloggerdata --limit 20 --json

filter — Advanced filtering

# Errors and warnings only
cli-anything-nslogger filter session.rawnsloggerdata --level 1

# By tag
cli-anything-nslogger filter session.rawnsloggerdata --tag Auth --tag Network

# Regex search
cli-anything-nslogger filter session.rawnsloggerdata --regex "(timeout|failed|error)"

# By thread
cli-anything-nslogger filter session.rawnsloggerdata --thread "main"

# JSON output
cli-anything-nslogger filter session.rawnsloggerdata --level 0 --json

export — Export to text/JSON/CSV

# JSON to stdout
cli-anything-nslogger export session.rawnsloggerdata --format json

# CSV to file
cli-anything-nslogger export session.rawnsloggerdata --format csv --output logs.csv

# Filtered text export
cli-anything-nslogger export session.rawnsloggerdata --format text --level 1 --tag Network

stats — Summary statistics

# Human-readable summary
cli-anything-nslogger stats session.rawnsloggerdata

# JSON for agent consumption
cli-anything-nslogger stats session.rawnsloggerdata --json

JSON output shape:

{
  "total": 342,
  "by_level": {"ERROR": 12, "WARNING": 34, "INFO": 200, "DEBUG": 96},
  "by_tag": {"Network": 89, "Auth": 45, "UI": 120},
  "by_thread": {"main": 200, "bg-queue": 142},
  "by_type": {"text": 340, "client_info": 1, "disconnect": 1},
  "clients": ["MyApp"],
  "first_timestamp": "2024-01-01T10:00:00+00:00",
  "last_timestamp": "2024-01-01T10:05:30+00:00",
  "duration_seconds": 330.0
}

listen — Receive live connections

# Match the NSLogger.app GUI Bonjour behavior for iOS auto-discovery
cli-anything-nslogger listen --bonjour --name bazinga --debug

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

# Write machine-readable JSON Lines
cli-anything-nslogger listen --bonjour --name bazinga --output app.jsonl --output-format jsonl

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

# Show only errors while listening, output as JSON stream
cli-anything-nslogger listen --bonjour --name bazinga --level 0 --json

# Run until Ctrl-C
cli-anything-nslogger listen --bonjour --name bazinga

Use Bonjour mode first for iOS apps because it matches the desktop NSLogger GUI: the CLI publishes a native macOS NetService with _nslogger-ssl._tcp and accepts TLS NSLogger frames. Use direct TCP/TLS only when the app is manually configured with the Mac host and port.

repl — Interactive Command REPL

cli-anything-nslogger repl session.rawnsloggerdata
# Or launch it by running cli-anything-nslogger with no subcommand.

Log Levels

Value	Name	Use for
0	ERROR	Unrecoverable failures
1	WARNING	Recoverable issues
2	INFO	Normal operation
3	DEBUG	Developer details
4	VERBOSE	Trace-level noise

Message JSON Shape

{
  "sequence": 42,
  "timestamp": "2024-01-01T10:01:23+00:00",
  "timestamp_ms": 456,
  "thread_id": "main",
  "tag": "Network",
  "level": 0,
  "level_name": "ERROR",
  "type": "text",
  "text": "Connection timed out after 30s",
  "image_width": 0,
  "image_height": 0,
  "client_name": "MyApp",
  "client_version": "2.1.0",
  "os_name": "iOS",
  "os_version": "17.0",
  "machine": "iPhone15,2"
}

Agent Workflow Examples

# 1. Inspect a captured crash session
cli-anything-nslogger stats crash.rawnsloggerdata --json

# 2. Find all errors in the 5 minutes before crash
cli-anything-nslogger filter crash.rawnsloggerdata --level 0 --json

# 3. Get network failures only
cli-anything-nslogger filter crash.rawnsloggerdata --tag Network --regex "fail|timeout|error" --json

# 4. Export full log for offline analysis
cli-anything-nslogger export crash.rawnsloggerdata --format json --output crash_log.json

# 5. Monitor an iOS app live and keep a local copy
cli-anything-nslogger listen --bonjour --name bazinga --output app.log --debug