cli AGENTS.md

AI Coding Agent Guidelines

For AI coding agents (Cursor, Copilot, Windsurf, Codex, etc.) working on this codebase.

Read these first — they are the source of truth:

• CLAUDE.md — Working principles, critical rules, learnings from past mistakes
• docs/ARCHITECTURE.md — Hexagonal architecture, project structure, package inventory
• docs/DEVELOPMENT.md — Build, test, lint, and CI commands (make ci, make ci-full, etc.)
• docs/COMMANDS.md — CLI command reference
• .claude/rules/go-quality.md — Go style, imports, error handling, modern patterns
• .claude/rules/testing.md — Test organization, coverage targets, rate limiting

Everything below supplements those docs with quick-reference examples. If anything here conflicts with the above, the above wins.

---

Quick Reference: Shared Helpers

Don't create package-local wrappers — use these directly:

// CLI client
client := common.GetNylasClient()
grantID := common.GetGrantID(args)

// Client helpers (reduce boilerplate)
common.WithClient(args, func(ctx, client, grantID) (T, error) {
    return client.DoSomething(ctx, grantID)
})
common.WithClientNoGrant(func(ctx, client) (T, error) {
    return client.DoSomething(ctx)
})

// Output
common.PrintSuccess("Email sent successfully")
common.PrintError("Failed to send email", err)
common.FormatSize(bytes)      // "1.5 MB"
common.FormatTimeAgo(time)    // "2 hours ago"
common.PrintJSON(data)        // Pretty-print JSON
out := common.GetOutputWriter(cmd)  // --json/--yaml/--quiet

// Flags
common.AddJSONFlag(cmd, &jsonOutput)   // --json
common.AddLimitFlag(cmd, &limit, 25)   // --limit/-n
common.AddYesFlag(cmd, &yes)           // --yes/-y
common.AddFormatFlag(cmd, &format)     // --format/-f

// Validation
common.ValidateRequired("event ID", eventID)
common.ValidateRequiredFlag("--to", toEmail)
common.ValidateEmail("recipient", email)
common.ValidateURL("webhook URL", webhookURL)
common.ValidateOneOf("status", status, []string{"pending", "active"})

// HTTP (in adapters)
httputil.WriteJSON(w, http.StatusOK, data)
body, err := httputil.LimitedBody(r, maxSize)

// AI (in adapters/ai/)
ConvertMessagesToMaps(messages)
ConvertToolsOpenAIFormat(tools)