NSLogger (CLI logs)

--- name: "cli-anything-nslogger" description: CLI harness for NSLogger : parse, filter, export, and monitor NSLogger log files (.rawnsloggerdata / .nsloggerdata) version: 0.1.0 install: pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=nslogger/agent-harness binary: cli-anything-nslogger tags: [logging, ios, macos, debugging, nslogger] --- # cli-anything-nslogger A complete CLI harness for [NSLogger](https://github.com/fpillet/NSLogger), the macOS log viewer for iOS/macOS apps. ## Installation ``bash cd nslogger/agent-harness pip install -e . # Verify cli-anything-nslogger --help ` ## Command Reference ### generate : Create sample files for testing `bash cli-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 `bash 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 `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 #