feat: add 'auth0 agent skills install' to set up Auth0 skills

.github/workflows/main.yml

@@ -3,7 +3,7 @@ name: Main Workflow
 on:
   pull_request: {}
   push:
-    branches: [ "main" ]
+    branches: [ "main", "beta" ]
 
 
 concurrency:
@@ -65,7 +65,9 @@ jobs:
     needs: unit-tests
 
     # Skip running if the PR is coming from a fork or is created by dependabot or snyk due to missing repo secrets.
-    if: github.event.pull_request.head.repo.fork == false && (github.actor != 'dependabot[bot]' && github.actor != 'snyk-bot')
+    # Only run on pushes to main or PRs targeting main.
+    if: github.event.pull_request.head.repo.fork == false && (github.actor != 'dependabot[bot]' && github.actor != 'snyk-bot') &&
+        (github.ref == 'refs/heads/main' || github.base_ref == 'main')
 
     steps:
       - name: Check out the code

.github/workflows/release-beta.yml

@@ -0,0 +1,39 @@
+name: Release Beta
+
+on:
+  push:
+    tags:
+      # Prerelease tags only, e.g. v1.2.3-beta.1. Stable releases such as
+      # v1.2.3 are handled by release.yml.
+      - "v[0-9]+.[0-9]+.[0-9]+-*"
+
+permissions:
+  contents: write
+
+jobs:
+  goreleaser:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
+        with:
+          fetch-depth: 0 # This ensures all history and tags are fetched
+          path: auth0-cli
+
+      - name: Set up Go
+        uses: actions/setup-go@be3c94b385c4f180051c996d336f57a34c397495 # v3.6.1
+        with:
+          go-version-file: auth0-cli/go.mod
+          check-latest: true
+
+      # GoReleaser automatically marks SemVer prerelease tags (those with a
+      # "-suffix") as GitHub prereleases. Homebrew and Scoop PRs are
+      # intentionally omitted so beta builds never reach package managers.
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@90a3faa9d0182683851fbfa97ca1a2cb983bfca3 # pin@6.2.1
+        with:
+          version: "2.7.0"
+          args: release --clean
+          workdir: 'auth0-cli'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}

.github/workflows/release.yml

@@ -3,7 +3,10 @@ name: Release
 on:
   push:
     tags:
-      - "v*"
+      # Stable releases only, e.g. v1.2.3. Prerelease tags such as
+      # v1.2.3-beta.1 are handled by release-beta.yml.
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
 
 permissions:
   contents: write
@@ -31,8 +34,7 @@ jobs:
           args: release --clean
           workdir: 'auth0-cli'
         env:
-          GITHUB_TOKEN: ${{ secrets.GORELEASER_GITHUB_TOKEN }}
-          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          GITHUB_TOKEN: ${{ github.token }}
 
       # Homebrew Tap Process
       - name: Checkout Homebrew Tap Repo

.github/workflows/security.yml

@@ -3,7 +3,7 @@ name: Security
 on:
   pull_request: {}
   push:
-    branches: [ "main" ]
+    branches: [ "main", "beta" ]
   schedule:
     - cron: "30 0 1,15 * *"
 

.goreleaser.yml

@@ -17,7 +17,6 @@ builds:
       - -X 'github.com/auth0/auth0-cli/internal/buildinfo.Revision={{.Commit}}'
       - -X 'github.com/auth0/auth0-cli/internal/buildinfo.BuildUser=goreleaser'
       - -X 'github.com/auth0/auth0-cli/internal/buildinfo.BuildDate={{.Date}}'
-      - -X 'github.com/auth0/auth0-cli/internal/instrumentation.SentryDSN={{.Env.SENTRY_DSN}}'
 archives:
   - name_template: '{{ .ProjectName }}_{{ .Version }}_{{ title .Os }}_{{ if eq .Arch "arm64" }}arm64{{ else }}x86_64{{ end }}'
     files:
@@ -32,6 +31,8 @@ snapshot:
   version_template: "{{ .Tag }}-SNAPSHOT-{{.ShortCommit}}"
 changelog:
   disable: true
+release:
+  replace_existing_draft: true
 brews:
   - name: auth0
     repository:
@@ -52,7 +53,7 @@ brews:
       (bash_completion/"auth0").write `#{bin}/auth0 completion bash`
       (fish_completion/"auth0.fish").write `#{bin}/auth0 completion fish`
       (zsh_completion/"_auth0").write `#{bin}/auth0 completion zsh`
-    caveats: "Thanks for installing the Auth0 CLI"
+    caveats: "Thanks for installing the Auth0 CLI\n\nTip: run 'auth0 agent skills install' to install the Auth0 skill for your AI coding assistants."
 
 scoops:
   - name: auth0
@@ -68,4 +69,4 @@ scoops:
     description: Build, manage and test your Auth0 integrations from the command line
     license: MIT
     skip_upload: true
-    post_install: ["Write-Host 'Thanks for installing the Auth0 CLI'"]
+    post_install: ["Write-Host 'Thanks for installing the Auth0 CLI'", "Write-Host \"Tip: run 'auth0 agent skills install' to install the Auth0 skill for your AI coding assistants.\""]

AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md
+
+This repository's guidelines for AI coding agents live in [CLAUDE.md](CLAUDE.md), the single source of truth.
+
+Read **@CLAUDE.md** for the project overview and working conventions. Detailed material lives under [`references/`](references/), linked from there.

CHANGELOG.md

@@ -8,6 +8,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+# [v1.32.0](https://github.com/auth0/auth0-cli/tree/v1.32.0) (June 23, 2026)
+
+[Full Changelog](https://github.com/auth0/auth0-cli/compare/v1.31.0...v1.32.0)
+
+### Added
+- Add agent-aware command analytics with success/failure tracking and AI agent detection [#1551]
+- Improve subscribe UX in `auth0 event-streams` [#1534]
+
+### Fixed
+- Fix `auth0 clients` to fetch `enabled_clients` from the dedicated endpoint [#1532]
+- Fix user login flow to skip refresh token support and avoid requesting `offline_access` [#1536]
+- Fix head tag clearing in `auth0 acul config set` [#1548]
+- Improve terraform plan failure error messaging [#1549]
+
 # [v1.31.0](https://github.com/auth0/auth0-cli/tree/v1.31.0) (May 22, 2026)
 
 [Full Changelog](https://github.com/auth0/auth0-cli/compare/v1.30.0...v1.31.0)
@@ -739,8 +753,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `auth0 tenants add` command in favor of `auth0 login` [#546]
 - Updating of action triggers which inevitably results in error [#597]
 
-
-[unreleased]: https://github.com/auth0/auth0-cli/compare/v1.31.0...HEAD
+[unreleased]: https://github.com/auth0/auth0-cli/compare/v1.32.0...HEAD
+[#1551]: https://github.com/auth0/auth0-cli/pull/1551
+[#1549]: https://github.com/auth0/auth0-cli/pull/1549
+[#1548]: https://github.com/auth0/auth0-cli/pull/1548
+[#1536]: https://github.com/auth0/auth0-cli/pull/1536
+[#1534]: https://github.com/auth0/auth0-cli/pull/1534
+[#1532]: https://github.com/auth0/auth0-cli/pull/1532
 [#1527]: https://github.com/auth0/auth0-cli/pull/1527
 [#1522]: https://github.com/auth0/auth0-cli/pull/1522
 [#1518]: https://github.com/auth0/auth0-cli/pull/1518

CLAUDE.md

@@ -0,0 +1,147 @@
+# 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.
+
+---
+
+## Working Principles
+
+Apply these on every task in this repo — they keep changes correct, small, and reviewable.
+
+- **Think before coding.** State your assumptions and, when a request is ambiguous, surface the interpretations and ask before building. Recommend a simpler approach when you see one. A clarifying question up front beats a wrong implementation.
+- **Simplicity first.** Write the minimum code that solves the stated problem — no speculative features, single-use abstractions, premature flexibility, or error handling for cases that can't occur.
+- **Surgical changes.** Touch only what the request requires. Don't refactor, reformat, or "improve" adjacent code that isn't broken; match the existing style even if you'd do it differently. Every changed line should trace directly to the request. Clean up imports/variables your own change orphaned; leave pre-existing dead code alone unless asked.
+- **Goal-driven execution.** Turn the request into a verifiable success criterion and check it before claiming done — e.g. "add a flag" becomes "add the flag, wire it through, add a table-driven test, and regenerate docs." Don't report success you haven't verified.
+
+---
+
+## Project Overview
+
+**auth0-cli** is the official command-line interface for Auth0 — build, manage, and test Auth0 integrations from the terminal.
+
+- **Language:** Go 1.25.8
+- **Tech Stack:** Cobra (commands) + pflag, go-auth0 Management SDK (v1 `management` and v2), Sentry crash reporting, zalando/go-keyring for secret storage, terraform-exec (Terraform export), charmbracelet/glamour (markdown rendering)
+- **Package Manager:** Go modules — **vendored** (`vendor/` is committed; run `go mod tidy && go mod vendor` after dependency changes)
+- **Minimum Platform Version:** Go 1.25.8 (from `go.mod`)
+- **Dependencies:** go-auth0 v1.44.0 + v2.14.0, spf13/cobra 1.10.2, getsentry/sentry-go 0.47.0, zalando/go-keyring 0.2.8 · test: stretchr/testify 1.11.1, golang/mock (gomock) 1.6.0
+
+---
+
+## 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](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](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](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](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](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](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/v2 go-auth0 split.
+
+See [references/pitfalls.md](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](references/docs-update.md) for the tracked-docs inventory and the code-to-docs mapping. Read it when your change touches user-facing behavior.