Guide

AI Agent Audit Logs with Nylas CLI

AI agents like Claude Code and GitHub Copilot can send emails, create calendar events, and read contacts on your behalf. Audit logging tracks every command they execute across Gmail, Outlook, Exchange, Yahoo, iCloud, and IMAP — automatically detecting the agent source, logging the grant and API request, and giving you per-session filtering and compliance exports.

By Caleb Geene

How do you audit AI agent activity?

Run nylas audit init --enable and every command that Claude Code, GitHub Copilot, or any MCP agent executes is logged automatically — the agent source, the grant used, the API request, and the outcome. No code changes, no wrappers, one command to start.

Why do AI agents need audit logs?

AI agents need audit logs because they run commands autonomously and you need a verifiable record of every action they took. Without audit logging, an agent session is a black box — you cannot prove what was accessed, changed, or sent. With audit logs, you get:

  • AI agent tracking — see exactly what Claude Code, GitHub Copilot, or custom MCP agents executed, with automatic source detection
  • Per-session filtering — review what an agent did during a specific coding session by time range and source
  • Compliance and security — SOC 2, HIPAA, and internal policies need evidence of who accessed what, including automated agents
  • CI/CD observability — trace pipeline failures back to the exact command, grant, and API request

How do I implement AI agent audit logs?

You implement AI agent audit logs by running a single CLI command that initializes local logging, auto-detects agent sources like Claude Code and GitHub Copilot, and starts recording every command execution with timestamps, grant IDs, and outcomes. Here is how to initialize and enable:

nylas audit init --enable

This creates the log directory, writes a default configuration, and starts recording. Verify it's active:

nylas audit logs status
Audit logging: enabled
Log path:      ~/.nylas/audit/
Retention:     90 days
Max size:      50 MB
Format:        json

You can also enable and disable logging independently:

# Disable temporarily
nylas audit logs disable

# Re-enable
nylas audit logs enable

What gets logged

Every command execution produces a log entry with these fields:

{
  "timestamp": "2026-03-04T14:32:01Z",
  "command": "nylas email send",
  "grant_id": "grant_abc123",
  "invoker": "qasim",
  "source": "claude-code",
  "request_id": "req_xyz789",
  "status": "success",
  "duration_ms": 1240
}
  • timestamp — ISO 8601, always UTC
  • command — the full command (arguments included, sensitive values redacted)
  • grant_id — which Nylas account was used
  • invoker — the user or system that ran the command
  • source — how the command was invoked: terminal, claude-code, github-actions, mcp, etc.
  • request_id — correlates to the Nylas API request for debugging
  • status — success or error
  • duration_ms — round-trip time in milliseconds

Sensitive data like API keys, access tokens, and email bodies are automatically redacted from log entries.

How do I view Claude Code audit logs?

You view Claude Code audit logs by filtering with --source claude-code. The audit system automatically detects when Claude Code invokes CLI commands via environment variables — no configuration needed. The source field is set automatically based on how the CLI was invoked.

# See everything Claude Code ran today
nylas audit logs show --source claude-code --since "2026-03-04"

# See all AI agent activity in the last week
nylas audit logs show --invoker claude-code --since "2026-02-25"

# Review a specific agent session by time window
nylas audit logs show --source mcp --since "2026-03-04T10:00:00" --until "2026-03-04T12:00:00"

# Filter agent errors only
nylas audit logs show --source claude-code --status error

This is especially useful after an AI coding session — review exactly which emails an agent read, which calendar events it created, and whether any API calls failed. If you're building your own agent with email tools, see the build an LLM agent guide for the subprocess pattern these logs capture. Supported agent sources include claude-code, github-copilot, mcp, and any custom agent that sets the NYLAS_CLI_SOURCE environment variable.

How do I filter AI agent audit logs?

You filter AI agent audit logs using flags on nylas audit logs show — by date range, command name, agent source, or status. Combine multiple filters to narrow down exactly what happened during a specific session or time window.

# Show the last 20 entries
nylas audit logs show -n 20

# Filter by date range
nylas audit logs show --since "2026-03-01" --until "2026-03-04"

# Filter by command
nylas audit logs show --command "email send"

# Filter by status
nylas audit logs show --status error

# Combine filters
nylas audit logs show --source github-actions --status error --since "2026-03-01"

Add --json to get machine-readable output for piping into other tools:

nylas audit logs show --json -n 100 | jq '.[] | select(.duration_ms > 5000)'

Summary statistics

Get a high-level overview of audit activity:

nylas audit logs summary --days 30
Audit Log Summary (last 30 days)
─────────────────────────────────
Total commands:    1,247
Success rate:      98.6%
Unique invokers:   4

Top commands:
  email send         412  (33.0%)
  email list         298  (23.9%)
  calendar list      187  (15.0%)
  event create        94  (7.5%)
  contacts list       82  (6.6%)

By source:
  terminal           687  (55.1%)
  claude-code        312  (25.0%)
  github-actions     198  (15.9%)
  mcp                 50  (4.0%)

Error breakdown:
  auth_expired         8
  rate_limited         6
  invalid_grant        3

Add --json to pipe the summary into dashboards or alerting systems:

nylas audit logs summary --days 7 --json

How do I export AI agent audit logs for compliance?

You export AI agent audit logs for compliance by running nylas audit exportwith a date range and format flag. The CLI outputs CSV for auditors or JSON for SIEM ingestion into Splunk, Datadog, or any system that accepts structured logs.

# CSV export for a specific quarter
nylas audit export --format csv --since "2026-01-01" --until "2026-03-31" --output Q1-audit.csv

# JSON export for SIEM ingestion
nylas audit export --format json --since "2026-03-01" --output march-audit.json

Automate quarterly exports with a simple script:

#!/bin/bash
# quarterly-audit-export.sh
QUARTER_START="2026-01-01"
QUARTER_END="2026-03-31"
OUTPUT="Q1-2026-audit.csv"

nylas audit export \
  --format csv \
  --since "$QUARTER_START" \
  --until "$QUARTER_END" \
  --output "$OUTPUT"

echo "Exported to $OUTPUT"

How do I add audit logging to CI/CD pipelines?

You add audit logging to CI/CD pipelines by running nylas audit init --enable --no-promptas an early step in your workflow. Every subsequent CLI command in the pipeline is logged automatically, and you can export the log as a build artifact for post-run review.

# .github/workflows/sync.yml
name: Calendar Sync
on:
  schedule:
    - cron: "0 9 * * 1"

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Install Nylas CLI
        run: npm install -g nylas-cli

      - name: Enable audit logging
        run: nylas audit init --enable --no-prompt

      - name: Sync calendars
        run: nylas calendar list --grant-id $GRANT_ID

      - name: Export audit log
        run: nylas audit export --format json --output audit.json

      - name: Upload audit artifact
        uses: actions/upload-artifact@v4
        with:
          name: audit-log
          path: audit.json

After the run, filter for pipeline activity:

nylas audit logs show --source github-actions --since "2026-03-04"

Configuration

View and adjust audit settings:

# View current configuration
nylas audit config show

# Set retention period (days)
nylas audit config set retention 180

# Set max log size (MB)
nylas audit config set max_size 100

# Change log directory
nylas audit config set path /var/log/nylas-audit

You can also set these during initialization:

nylas audit init --retention 180 --max-size 100 --path /var/log/nylas-audit --enable

How do I monitor AI coding assistant activity?

You monitor AI coding assistant activity by combining audit logs with summary statistics to catch anomalies early — a spike in error rates, an unexpected agent source, or commands running outside business hours. Use nylas audit logs summary --days 7 for a weekly health check, and pipe JSON exports into your existing monitoring stack:

# Weekly health check
nylas audit logs summary --days 7

# Alert on high error rates
nylas audit logs show --status error --since "$(date -v-1d +%Y-%m-%d)" --json | jq length

# Monitor specific agents
nylas audit logs show --source claude-code --json | jq 'group_by(.command) | map({command: .[0].command, count: length})'

Frequently asked questions

What are AI agent audit logs?
AI agent audit logs are structured records of every action an AI coding assistant takes — commands executed, APIs called, grants used, and outcomes. They provide a verifiable trail for security reviews, compliance audits, and debugging.
Does audit logging affect CLI performance?
No. Logs are written asynchronously to a local file. Typical overhead is under 1ms per command.
What AI agents are detected automatically?
Claude Code, GitHub Copilot, GitHub Actions, and any MCP-based agent. Custom agents can set the NYLAS_CLI_SOURCE environment variable to identify themselves.
Are email bodies or API keys logged?
No. Sensitive data is automatically redacted. Only the command name, flags, grant ID, status, and timing are recorded.
Can I send audit logs to a SIEM?
Yes. Use nylas audit export --format json to generate files for ingestion into Splunk, Datadog, or any SIEM that accepts JSON.
How long are logs retained?
Default is 90 days. Change with nylas audit config set retention 180 for up to a year.

Next steps