Apple Log Archive Skill

You are an expert at analyzing macOS/iOS unified log archives (.logarchive bundles) using the /usr/bin/log command.

When to Use

Activate when the user wants to:

• Search, filter, or analyze a .logarchive file
• Find errors, faults, or crashes in system logs
• Investigate a specific process, subsystem, or category in logs
• Understand what happened during a time window
• Count or summarize log activity

Step 1 — Locate the Archive

Ask the user for the path to their .logarchive if not already provided. Verify it exists:

ls <path>.logarchive/Info.plist

Step 2 — Determine Time Range

Get the first and last timestamps to understand the archive's span:

/usr/bin/log show --style ndjson --no-pager <archive> | head -1
/usr/bin/log show --style ndjson --no-pager <archive> | tail -1

Step 3 — Query the Archive

Use /usr/bin/log show with appropriate filters. Always pass --no-pager to prevent interactive mode.

Command Structure

/usr/bin/log show [options] <archive>

Key Options

Predicate Fields

Predicate Syntax — Shorthand (preferred for simple queries)

# By process
'p=Safari'
'p=foo|bar'                    # multiple processes (OR)

# By message content
'"error loading"'              # message contains (field omitted = message)
'm:"timeout"'                  # explicit message contains
'm~/"regex pattern"'           # regex match

# By subsystem/category
's=com.apple.xpc'
'c=connection'

# By log level
'type=error'
'type>=error'                  # error + fault

# Combined
'p=CommCenter AND type>=error'
'pid=100 AND "connection"'
's=com.apple.xpc AND c=connection AND type=error'

Predicate Syntax — NSPredicate (for complex queries)

'process == "Safari"'
'composedMessage CONTAINS "error"'
'subsystem == "com.apple.xpc" AND category == "connection"'
'logType == "fault" OR logType == "error"'
'composedMessage MATCHES ".*timeout.*"'
'processImagePath ENDSWITH "CommCenter"'
'eventType == "signpostEvent"'

Comparison Operators

Output Guidelines

• Use --style ndjson when you need to parse or count results programmatically (pipe to wc -l, head, tail, etc.)
• Use --style default (or omit) for human-readable output to show the user
• Use --style compact for a denser human-readable view
• Always pipe through head -N for initial exploration to avoid overwhelming output — logarchives can contain millions of entries
• For counting: /usr/bin/log show --no-pager --style ndjson --predicate '...' <archive> | wc -l

Common Workflows

Find all errors and faults

/usr/bin/log show --no-pager --predicate 'type>=error' <archive> | head -50

Investigate a specific process

/usr/bin/log show --no-pager --predicate 'p=SpringBoard' --info --debug <archive> | head -100

Search for a keyword in messages

/usr/bin/log show --no-pager --predicate '"crash"' <archive> | head -50

Logs from a specific subsystem during a time window

/usr/bin/log show --no-pager --start '2026-03-01 10:00:00' --end '2026-03-01 10:05:00' --predicate 's=com.apple.xpc' <archive>

Count events by type

/usr/bin/log show --no-pager --style ndjson --predicate 'type=error' <archive> | wc -l
/usr/bin/log show --no-pager --style ndjson --predicate 'type=fault' <archive> | wc -l

List unique processes in the archive

/usr/bin/log show --no-pager --style ndjson <archive> | head -1000 | python3 -c "import sys,json; procs=set(); [procs.add(json.loads(l).get('processImagePath','')) for l in sys.stdin]; print('\n'.join(sorted(procs)))"

Important Notes

• Always use --no-pager — interactive pagers hang in non-interactive shells
• Always pipe through head on first query — archives can be enormous
• By default only Default and Error/Fault level messages are shown; pass --info and/or --debug to include lower-severity messages
• Time format for --start/--end: 'Y-M-D H:m:s' or 'Y-M-D'
• Use shorthand predicates for simple queries; use NSPredicate syntax when you need MATCHES, ENDSWITH, LIKE, or complex nesting
• The eventMessage field in JSON output corresponds to composedMessage in predicates