olkcli: Instructions file for Claude Code

CLAUDE.md

This file provides context for Claude Code when working on the olk project.

What is this project?

olk is a CLI tool for Microsoft Outlook and OneDrive via the Microsoft Graph API. It provides terminal access to email, calendar, contacts, tasks, and OneDrive files for both personal Microsoft accounts and enterprise Azure AD/Entra ID accounts.

Quick Reference

make build          # Build ./bin/olk (olk-dev namespace: own config and keychain entries)
make test           # Run tests
make lint           # Lint with golangci-lint
go mod tidy         # After changing dependencies

Validating on macOS: running a freshly built ./bin/olk against a real account triggers a macOS Keychain access prompt (each build is a new identity). A human must click "Always Allow" — you (an agent) can't dismiss the dialog, so don't treat a first-run hang as a bug; ask the user to approve it.

Architecture

• CLI framework: github.com/alecthomas/kong — commands are Go structs with Run(ctx *RunContext) error
• Auth: Raw OAuth2 against login.microsoftonline.com — no MSAL. Two flows: device code (default) and authorization-code + PKCE via system browser with a loopback listener (--browser, in internal/msauth/authcode.go) for tenants whose Conditional Access requires a compliant device or blocks device code. Both use PKCE (RFC 7636). Scopes defined in internal/msauth/scopes.go. Enterprise-only scopes (MailboxSettings.ReadWrite, User.ReadBasic.All) are only requested with --enterprise flag — personal accounts cannot consent to them. Token refresh is serialized per-email via sync.Map of mutexes to prevent race conditions
• API: Official msgraph-sdk-go wrapped in internal/graphapi/ for ergonomic access
• Secrets: OS keyring via github.com/99designs/keyring (macOS Keychain, Linux Secret Service, Windows WinCred). File-backend password prompt writes to stderr (not stdout) to avoid corrupting piped output. Set OLK_KEYRING_PASSWORD for headless/non-interactive use
• Output: JSON envelope (--json), aligned table (default), TSV (--plain)
• Provider parity: calendar JSON supports opt-in --body-format text|html, stable/lifecycle metadata, structured attendee responses, and lossless recurrence details. Mail and contact list/get/delta results expose provider synchronization IDs and timestamps. Calendar writes support --transaction-id, --no-reminder, --location none, and --all-day/--timed with validation.
• MCP server: olk mcp (in internal/cmd/mcp*.go) runs a stdio Model Context Protocol server exposing a curated allowlist of read-first tools (curatedTools in mcp_server.go) — NOT the whole command tree. Tool calls reparse a rebuilt argv and run in-process with stdout captured under a mutex (mcp_capture.go). Read-only by default; --allow-write <tool> exposes a named curated safe-write tool (per-tool opt-in). Local file saves (attachments, .eml) are confined to --download-dir and refused without it (save_scope.go; commands write via ctx.saveDir/ctx.saveFile). No HTTP transport
• Capability guards: --no-write/--no-send are enforced once at the graphapi.Client layer (ensureWritable/ensureMaySend), so the guarantee holds across CLI, MCP, and scripts. --enable-commands[-exact]/--disable-commands gate dispatch via commandAllowed() (commands.go), checked in Execute() and reused to filter the MCP registry. --wrap-untrusted wraps untrusted:"true"-tagged struct fields in JSON/plain output (internal/outfmt/untrusted.go)
• Timezone: Display-layer conversion via outfmt.ConvertTime(). Resolved once per command via RunContext.Timezone() (flag > env > config > Local). JSON output emits UTC timestamps as RFC3339 with a Z suffix (normalized via normalizeGraphUTC — Graph's DateTimeTimeZone.dateTime strings lack a zone); envelope includes timezone field. IANA db embedded via import _ "time/tzdata"