feat(audit): add audit logging with invoker identity tracking (#21)

Author: mqasimca

cmd/nylas/main.go

@@ -9,6 +9,7 @@ import (
 	"github.com/nylas/cli/internal/cli"
 	"github.com/nylas/cli/internal/cli/admin"
 	"github.com/nylas/cli/internal/cli/ai"
+	"github.com/nylas/cli/internal/cli/audit"
 	"github.com/nylas/cli/internal/cli/auth"
 	"github.com/nylas/cli/internal/cli/calendar"
 	"github.com/nylas/cli/internal/cli/config"
@@ -34,6 +35,7 @@ func main() {
 	// Enable command typo suggestions (e.g., "Did you mean 'email'?")
 	rootCmd.SuggestionsMinimumDistance = 2
 	rootCmd.AddCommand(ai.NewAICmd())
+	rootCmd.AddCommand(audit.NewAuditCmd())
 	rootCmd.AddCommand(auth.NewAuthCmd())
 	rootCmd.AddCommand(config.NewConfigCmd())
 	rootCmd.AddCommand(otp.NewOTPCmd())
@@ -55,6 +57,7 @@ func main() {
 	rootCmd.AddCommand(update.NewUpdateCmd())
 
 	if err := cli.Execute(); err != nil {
+		cli.LogAuditError(err)
 		fmt.Fprintln(os.Stderr, "Error:", err)
 		os.Exit(1)
 	}

docs/COMMANDS.md

@@ -693,6 +693,51 @@ nylas admin grants stats                              # Grant statistics
 
 ---
 
+## Audit Logging
+
+Track CLI command execution for compliance, debugging, and AI agent monitoring.
+
+```bash
+# Setup
+nylas audit init                              # Interactive setup
+nylas audit init --enable                     # Quick setup with defaults
+nylas audit logs enable                       # Enable logging
+nylas audit logs disable                      # Disable logging
+nylas audit logs status                       # Check status
+
+# View logs
+nylas audit logs show                         # Show last 20 entries
+nylas audit logs show --limit 50              # More entries
+nylas audit logs show --command email         # Filter by command
+nylas audit logs show --invoker alice         # Filter by username
+nylas audit logs show --source claude-code    # Filter by source (AI agents, etc.)
+nylas audit logs show --status error          # Filter by status
+nylas audit logs show --request-id req_abc123 # Find by Nylas request ID
+
+# Statistics and export
+nylas audit logs summary                      # Summary for last 7 days
+nylas audit logs summary --days 30            # Summary for 30 days
+nylas audit export --output audit.json        # Export to JSON
+nylas audit export --output audit.csv         # Export to CSV
+
+# Configuration
+nylas audit config show                       # Show configuration
+nylas audit config set retention_days 30      # Set retention
+nylas audit logs clear                        # Clear all logs
+```
+
+**Invoker detection:** Automatically tracks who ran commands:
+- `terminal` - Interactive terminal session
+- `claude-code` - Anthropic's Claude Code
+- `github-copilot` - GitHub Copilot CLI
+- `ssh` - Remote SSH session
+- `script` - Non-interactive automation
+- Custom via `NYLAS_INVOKER_SOURCE` env var
+
+**Details:** `docs/commands/audit.md`
+
+---
+
 ## Utility Commands
 
 ```bash
@@ -735,6 +780,7 @@ All commands follow consistent pattern:
 - Admin: `docs/commands/admin.md`
 - Workflows: `docs/commands/workflows.md` (OTP, automation)
 - Timezone: `docs/commands/timezone.md`
+- Audit: `docs/commands/audit.md`
 - AI: `docs/commands/ai.md`
 - MCP: `docs/commands/mcp.md`
 - TUI: `docs/commands/tui.md`

docs/INDEX.md

@@ -73,6 +73,7 @@ Quick navigation guide to find the right documentation for your needs.
 - **Scheduler** → [commands/scheduler.md](commands/scheduler.md)
 - **Admin** → [commands/admin.md](commands/admin.md)
 - **Timezone** → [commands/timezone.md](commands/timezone.md)
+- **Audit** → [commands/audit.md](commands/audit.md)
 - **TUI** → [commands/tui.md](commands/tui.md)
 - **Workflows (OTP)** → [commands/workflows.md](commands/workflows.md)
 - **Templates** → [commands/templates.md](commands/templates.md)
@@ -119,7 +120,7 @@ docs/
 ├── ARCHITECTURE.md        # System design
 ├── DEVELOPMENT.md         # Development setup
 │
-├── commands/              # Detailed command guides (16 files)
+├── commands/              # Detailed command guides (17 files)
 │   ├── ai.md              # AI features
 │   ├── mcp.md             # MCP integration
 │   ├── calendar.md        # Calendar events
@@ -133,6 +134,7 @@ docs/
 │   ├── scheduler.md       # Booking pages
 │   ├── admin.md           # API management
 │   ├── timezone.md        # Timezone utilities
+│   ├── audit.md           # Audit logging & invoker tracking
 │   ├── tui.md             # Terminal UI
 │   ├── templates.md       # Email templates
 │   └── workflows.md       # OTP & automation
@@ -206,4 +208,4 @@ docs/
 
 ---
 
-**Last Updated:** February 4, 2026
+**Last Updated:** February 5, 2026