cli-anything-nslogger

cli-anything-nslogger

面向 NSLogger 的完整命令行工具集，NSLogger 是用于 iOS/macOS 应用的 macOS 日志查看器。

安装

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

命令参考

generate — 创建用于测试的示例文件

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

read — 显示文件中的消息

# 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 — 高级过滤

# 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 — 导出为 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 — 汇总统计

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

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

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 — 接收实时连接

# 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

对于 iOS 应用，请先使用 Bonjour 模式，因为它与桌面版 NSLogger GUI 相匹配： 命令行工具会发布一个使用 _nslogger-ssl._tcp 的原生 macOS NetService，并 接受 TLS NSLogger 帧。仅当应用手动配置了 Mac 主机和端口时，才使用直接 TCP/TLS。

repl — 交互式命令 REPL

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

日志级别

值	名称	用途
0	ERROR	不可恢复的故障
1	WARNING	可恢复的问题
2	INFO	正常运行
3	DEBUG	开发者详细信息
4	VERBOSE	跟踪级噪声

消息 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 工作流示例

# 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