Viewing Logs

shellfirm provides built-in commands for viewing and searching audit logs, plus the JSON-lines format works well with standard Unix tools like jq.

Listing events

View all audit events:

shellfirm audit list

This outputs all recorded events in a readable format.

Searching events

Search for events matching specific criteria:

# Search by outcome
shellfirm audit search --outcome denied

# Search by agent session
shellfirm audit search --session sess-abc-123

Using jq for advanced queries

Since the audit log is JSON-lines, jq is a powerful tool for analysis.

View all events (formatted)

cat ~/.shellfirm/audit.log | jq .

Filter by outcome

# All denied commands
cat ~/.shellfirm/audit.log | jq -c 'select(.outcome == "DENIED")'

# All allowed commands
cat ~/.shellfirm/audit.log | jq -c 'select(.outcome == "ALLOWED")'

# All cancelled (user hit Ctrl+C)
cat ~/.shellfirm/audit.log | jq -c 'select(.outcome == "CANCELLED")'

Filter by severity

# Critical severity events
cat ~/.shellfirm/audit.log | jq -c 'select(.severity == "Critical")'

# High and Critical
cat ~/.shellfirm/audit.log | jq -c 'select(.severity == "High" or .severity == "Critical")'

Filter by pattern

# Events matching a specific pattern
cat ~/.shellfirm/audit.log | jq -c 'select(.matched_ids | index("git:force_push"))'

# Events from a specific check group
cat ~/.shellfirm/audit.log | jq -c 'select(.matched_ids[] | startswith("git:"))'

Filter by context

# Commands run on the main branch
cat ~/.shellfirm/audit.log | jq -c 'select(.context_labels | index("branch=main"))'

# Commands run over SSH
cat ~/.shellfirm/audit.log | jq -c 'select(.context_labels | index("ssh=true"))'

# Commands run as root
cat ~/.shellfirm/audit.log | jq -c 'select(.context_labels | index("root=true"))'

Filter by time

# Events from today
cat ~/.shellfirm/audit.log | jq -c 'select(.timestamp | startswith("2026-02-23"))'

# Events from the last hour (approximate)
cat ~/.shellfirm/audit.log | jq -c 'select(.timestamp > "2026-02-23T13:00:00Z")'

Filter by agent

# All commands from AI agents
cat ~/.shellfirm/audit.log | jq -c 'select(.agent_session_id != null)'

# Commands from a specific agent session
cat ~/.shellfirm/audit.log | jq -c 'select(.agent_session_id == "sess-xyz-789")'

Aggregation queries

# Count events by outcome
cat ~/.shellfirm/audit.log | jq -r '.outcome' | sort | uniq -c | sort -rn

# Most frequently triggered patterns
cat ~/.shellfirm/audit.log | jq -r '.matched_ids[]' | sort | uniq -c | sort -rn

# Commands by severity
cat ~/.shellfirm/audit.log | jq -r '.severity' | sort | uniq -c | sort -rn

# Daily event counts
cat ~/.shellfirm/audit.log | jq -r '.timestamp[:10]' | sort | uniq -c

Extracting useful reports

# Denied commands with reasons (table format)
cat ~/.shellfirm/audit.log | jq -r 'select(.outcome == "DENIED") | [.timestamp, .command, (.matched_ids | join(",")), .severity] | @tsv'

# Agent activity summary
cat ~/.shellfirm/audit.log | jq -r 'select(.agent_session_id != null) | [.agent_session_id, .outcome, .command[:50]] | @tsv' | column -t

Clearing the log

To delete the entire audit log:

shellfirm audit clear

This permanently removes all recorded events. Consider backing up the log first if you need the data for compliance.