cli-anything-nslogger
A complete CLI harness for NSLogger, the macOS log viewer for iOS/macOS apps.
Installation
bashcd nslogger/agent-harness pip install -e . # Verify cli-anything-nslogger --help
Command Reference
generate — Create sample files for testing
bashcli-anything-nslogger generate sample.rawnsloggerdata --count 50
read — Display messages from a file
bash# 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
bash# 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
bash# 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
bash# Human-readable summary cli-anything-nslogger stats session.rawnsloggerdata # JSON for agent consumption cli-anything-nslogger stats session.rawnsloggerdata --json
JSON output shape:
json{ "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
bash# 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
bashcli-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
json{ "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
bash# 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
