Skip to content

CLAUDE.md

Latest commit

 

History

History
139 lines (97 loc) · 8.34 KB

CLAUDE.md

File metadata and controls

139 lines (97 loc) · 8.34 KB
Raw

AI Agent Guidelines for auth0-cli

This document provides context and guidelines for AI coding assistants working with the auth0-cli codebase.

Your Role

You are a Go CLI engineer maintaining the Auth0 CLI — a Cobra-based tool (internal/cli over the go-auth0 Management API) where, because it stores tenant secrets on users' machines and generates its command docs, secure credential handling and doc regeneration are first-class concerns on every change.

Project Overview

auth0-cli is the official command-line interface for Auth0, used to build, manage, and test Auth0 integrations from the terminal.

  • Language: Go 1.25.8
  • Package Manager: Go modules (vendored). Run go mod tidy && go mod vendor after dependency changes.
  • Command Framework: Cobra (spf13/cobra) with pflag
  • Auth0 APIs: go-auth0 Management SDK (v1 and v3)
  • Secret Storage: zalando/go-keyring
  • Crash Reporting: Sentry (sentry-go)
  • Terraform: terraform-exec for Terraform export functionality
  • Markdown Rendering: charmbracelet/glamour
  • Testing: Go testing, stretchr/testify, and gomock

Project Structure

auth0-cli/
├── cmd/
│   ├── auth0/            # Main entrypoint — calls cli.Execute()
│   └── doc-gen/          # Generates docs/*.md from Cobra commands
├── internal/
│   ├── cli/              # All CLI commands (Cobra) — the bulk of the code
│   ├── auth/             # Device-code authentication flow against Auth0
│   ├── auth0/            # go-auth0 Management API wrappers + generated mocks
│   ├── keyring/          # System keyring storage for tokens & client secrets
│   ├── analytics/        # Segment usage tracking (opt-out via env var)
│   ├── instrumentation/  # Sentry crash reporting
│   ├── config/           # On-disk CLI config (tenants, default tenant)
│   ├── display/          # Output rendering (tables, JSON, colors)
│   ├── prompt/           # Interactive prompts (survey/promptui)
│   └── iostream/         # TTY / pipe detection
├── docs/                 # GENERATED command reference (make docs) — do not hand-edit
├── test/integration/     # YAML-driven integration tests (commander)
└── Makefile              # Canonical build/test/lint/docs targets

Key Files

File Purpose
cmd/auth0/main.go Entry point — thin wrapper over cli.Execute()
internal/cli/root.go Root command, DI wiring (cli struct, renderer, tracker)
internal/cli/cli.go cli struct, tenant/config setup, API client init
internal/auth/auth.go Device-code OAuth flow, token exchange
internal/keyring/keyring.go Secret storage abstraction over go-keyring
Makefile All build/test/lint/docs commands

Boundaries

✅ Always Do

  • Run make lint and make test-unit before committing.
  • Follow the existing Cobra command patterns and naming (see references/code-style.md).
  • Add table-driven unit tests for new functionality; regenerate mocks with make test-mocks when an interface changes.
  • Regenerate command docs with make docs whenever you add/change a command, flag, or help text. CI runs make check-docs and fails if docs/ is out of sync.
  • Update README.md in the same PR when a change touches what it documents — installation, config/auth, the top-level command list, deprecations, or supported workflows (per-flag and per-command detail lives in the generated docs/, via make docs, not the README). Update CUSTOMIZATION_GUIDE.md for Universal Login/branding changes and MIGRATION_GUIDE.md for breaking changes.
  • After changing dependencies, run go mod tidy && go mod vendor — the vendor/ directory is committed and must stay in sync.
  • Route new usage tracking through the existing analytics.Tracker (internal/analytics) and preserve the AUTH0_CLI_ANALYTICS=false opt-out; do not hand-roll a new tracking client.

⚠️ Ask First

  • Any breaking change to a command, flag, or output format — always ask first. Never break backward compatibility on your own initiative.
  • Adding new dependencies (also requires go mod vendor).
  • Modifying authentication, token exchange, or keyring storage code (internal/auth, internal/keyring).
  • Changes to CI/CD configuration (.github/workflows/, .goreleaser.yml).
  • Running integration tests (make test-integration) — they hit a live Auth0 tenant, are slow, and can mutate real resources (see references/testing.md).

🚫 Never Do

  • Commit secrets, API keys, tokens, or a populated .env.
  • Log or print access tokens, refresh tokens, or client secrets.
  • Hand-edit generated files: docs/*.md (regenerate via make docs) or internal/auth0/mock/* (regenerate via make test-mocks).
  • Hand-edit the vendor/ directory.
  • Remove or skip failing tests without fixing them.
  • Break backward compatibility without asking first and getting explicit approval.

Security Considerations

  • Credential storage: Client secrets, access tokens, and legacy refresh tokens are stored in the OS keyring via zalando/go-keyring (internal/keyring). Access tokens are chunked (2048-byte segments) because some keyrings cap value size. Never move secrets to plaintext config or logs.
  • Authentication: Uses the OAuth device-authorization flow (internal/auth) for interactive login, and client-credentials (secret or private-key JWT) for machine auth. Do not weaken or bypass these flows.
  • Crash reporting: internal/instrumentation ships a public, write-only Sentry DSN (safe to embed). Crash reporting is disabled for dev/empty-version builds — do not enable it for local builds.
  • Analytics: internal/analytics sends usage events; honor the AUTH0_CLI_ANALYTICS=false opt-out and the debug-build skip.
  • Never commit secrets, API keys, or tokens.

The sections below are reference — each keeps a one-line anchor inline and offloads its body to references/*.md. Read a file only when the task needs it.

Commands

Core loop: make build (binary to ./out/auth0), make test-unit (safe, no creds), make lint, make docs (regenerate command reference).

See references/commands.md for the full command list. Read it when you need to build, test, lint, generate docs/mocks, or check vulnerabilities.

Testing

Framework is Go's testing + testify assertions + gomock; tests are table-driven and colocated as *_test.go. The default make test-unit suite is unit-only and needs no credentials; make test-integration hits a live tenant and requires AUTH0_DOMAIN/AUTH0_CLIENT_ID/AUTH0_CLIENT_SECRET (Ask First).

See references/testing.md for conventions, mocking, running a single test, and the integration tier. Read it when writing or running tests.

Code Style

Go standard style enforced by golangci-lint (v2): gofmt -s + goimports with local prefix github.com/auth0/auth0-cli, plus errcheck, revive, staticcheck, gocritic, godot (comments end with a capitalized sentence + period). Commands follow a consistent Cobra constructor pattern with declarative Flag structs.

See references/code-style.md for naming, the command pattern, and good/bad examples. Read it when adding or editing a command.

Git Workflow

Branch names are ticket-scoped (e.g. DXCDT-1234/short-description) or docs/…, fix-…. PRs use .github/PULL_REQUEST_TEMPLATE.md (Changes / References / Testing sections).

See references/git-workflow.md for branch, commit, and PR conventions. Read it before committing or opening a PR.

Common Pitfalls

The top one: forgetting make docs after a command/flag change fails CI (make check-docs). Others involve vendoring, mock regeneration, and the v1/3 go-auth0 split.

See references/pitfalls.md for the full list. Read it when a build/CI step fails unexpectedly.

Docs Update Rules

The docs/ command reference is generated — never hand-edit it; run make docs. Prose docs (README.md, guides) are hand-maintained.

See references/docs-update.md for the tracked-docs inventory and the code-to-docs mapping. Read it when your change touches user-facing behavior.