[jacobovidal]

🔧 Changes

Replaces the basic auth0 universal-portals setup with a full native Go implementation, and adds auth0 universal-portals audit. Nothing here needs Node or an external tool: everything runs inside the CLI on top of the existing go-auth0 clients. go.mod and go.sum are unchanged.

setup

• Two templates: consumer (end users manage their account) and business (organization administrators manage their organization). Interactive by default; --no-input plus flags for scripts.
• Checks the logged-in session's permissions before it creates anything, and says which scopes are missing and how to add them (15 probes for consumer, 23 for business).
• Creates or reuses the application, grants, forms vault, forms and the portal. A rerun after a failure resumes, and a rerun after success changes nothing.
• --dry-run runs the whole flow against the tenant's real state, keeps the writes instead of sending them (placeholder ids, secrets redacted) and prints them.
• --json output is the same content and key order as the previous tool's, with 4-space indentation.

audit <portal-id>

• 24 rules for the portal and its application, each an error or a warning. Fails on errors, or on warnings too with --strict.
• Interactive fix menu, or --fix to apply every fix the CLI can make. Warnings are never changed because they may be intentional.
• --organization also checks that the portal and its application share a connection with the organization.

Options are checked before anything is sent. Setup checks the template, the name, the slug and, for a business portal that cannot ask, the user, before the permission check. An empty slug is made from the name, and a name made of spaces is refused. The cobra command only maps flags to options, and keeps the one rule that is about flags: the flags a run that cannot ask must be given.

Behavior change (beta only). The previous setup created three resources from --name and --slug. The new one keeps both flags (-n, -s) and does a superset of the work, but it also asks for --template when interactive and fails with a usage error under --no-input without it. Exit codes follow the CLI: 1 for errors including usage errors, 130 on interrupt.

Structure

• internal/portals is the domain package: the portal model, 12 small store interfaces, setup, business setup, audit, the rules and fixes, the terminal-agnostic Reporter/Prompter interfaces, and an in-memory fake tenant (portalstest). It imports no cobra, renderer or SDK. Precedent for a domain package: internal/openapi, internal/auth.
• internal/cli/universal_portals_*.go is the thin layer: cobra commands, the survey prompter, the terminal renderer, the error mapping, the dry-run transport, and the tenant adapters that implement the stores over cli.api and cli.apiv3. Typed SDK calls are used wherever one exists; raw requests only for portals, form import and read, and the permission probes.
• No new dependencies. The UI uses survey, the spinner and internal/ansi already in the module.

Shared files touched (outside the new command):

• internal/cli/management.go: the client builders accept an HTTP client, so the dry-run transport can wrap them.
• internal/cli/cli.go, internal/cli/auth_env.go: keep the domain, token and metadata needed by the portals adapters.
• internal/cli/utils_shared.go: removes three helpers only the old setup used.
• internal/auth0: new wrappers (UserAPI.Organizations, organization add and assign, ClientConnectionAPIV3) and regenerated mocks.
• docs/: regenerated with make docs.

Known difference between setup and audit. On a rerun, setup resets the callback and logout URLs of the application to its own list, while audit P012 only adds the callback that is missing. Both are pinned by tests and left as they are. If a person adds a URL by hand, a rerun of setup removes it. Say if you want setup to keep extra URLs, with the catch that the old tenant-domain callback then stays after a custom domain goes live.

Deviations from the previous tool, all deliberate: a slug that another portal uses is reported as a validation error with the reason slug_taken; P010 on an application whose only grant is client_credentials prints the command to run, because the CLI has no grant to leave it with; P008 says the tenant has "no custom domain", which is what it checks; usage errors exit 1 (CLI convention); agent mode without --json now emits JSON; client-credentials scope advice with no named scope lists every required scope; a failed audit also prints "The audit failed: N error(s)." from the root error handler, which is how the CLI exits 1.

📚 References

• Supersedes chore(portals): import the universal-portals source (Beta) #1738, feat(portals): call the Auth0 CLI from the tool and bundle it (Beta) #1739 and feat(cli): run universal-portals from an embedded tool (Beta) #1740.
• The --dry-run design comes from work by Bharath Natarajan, and the permission and scope checks from work by ramya18101. Both are credited with Co-authored-by trailers on the commits that carry their code.

🔬 Testing

Unit tests run with no credentials and no network: go test ./... -count=1 and make lint both pass.

Area	What it covers
internal/portals	Setup for both templates (create, reuse, resume, failure paths); permission probes and scope advice, including a test that the declared scopes cover every request; all 24 audit rules, the fixes, and the fix rounds; error classes; embedded form and template data; the portal model keeping unknown JSON fields.
internal/portals/portalstest	In-memory tenant and scripted prompter/reporter used by the tests above.
internal/cli	Flags, usage errors and the fix menu through the real cobra commands; the tenant adapters against local HTTP servers; the dry-run transport (reads pass through, writes are kept, secrets redacted); the exact --json output; the terminal renderer.

A contract test runs the same "a setting left empty is not sent" cases against the in-memory tenant and the adapter over the SDK, so the fake the flow tests run on cannot drift from the requests the API receives. A test requires a probe for every write that a first run, a rerun and a business run with a new organization and role make. The business dry run is tested end to end through the transport.

Because the go-auth0 client mutates a package-level map when it is built, tests that build CLI clients do not run in parallel.

Run against a real tenant, twice: once on the first version of this branch, and again after the review fixes (the last commits). It was a throwaway test tenant with a ready custom domain. Everything created was deleted afterwards and each delete was checked with a 404, and a before/after snapshot of applications, resource servers, grants, vault connections, forms, portals, organizations, roles and flows matched both times.

On the first version:

• Usage errors, a slug clash and a missing portal exit 1 and write nothing.
• --dry-run for consumer writes nothing.
• setup for consumer and business created the application, grants and portal, reused the existing resource servers, forms and (for business) the vault; a rerun reused everything with the same ids.
• audit of the new portals reported no findings. After breaking the application and sidebar by hand (refresh token rotation on, client_credentials added, a legacy sidebar link), audit reported the three errors and two warnings, audit --fix cleared them, and a final audit was clean.
• The organization member roles request was rejected for its empty payload (400) and not for permissions (403), so the token had create:organization_member_roles. That scope is not in the required-scope list, which was carried over from the previous tool. Left as is; say if you want it added.

After the review fixes, the second run covered what changed:

• Slug clash, blank name, bad slug and unknown template stop with the new messages and reasons and write nothing. The clash only gets as far as slug_taken after the permission check, so the live API accepted the new update client probe.
• --dry-run for consumer and for business passed the permission check, including the business-only probes, and wrote nothing. The only value of a secret field in the output is the placeholder.
• setup and a rerun for consumer created and then reused the same resources.
• After the same breaks as before, audit --fix cleared the findings. With client_credentials as the only grant, audit printed a command instead of offering a fix, --fix left the grant alone, and running the printed command restored the application and a clean audit.

Not tested

• The form import path and its flow against the real API: the tenant already had forms with the same names, which setup reuses.
• A real business setup after the review fixes. Only its dry run ran against the tenant, which covers the new member-role probe, but not the role assignment itself.
• Interactive prompts, the fix menu, Ctrl+C mid-run and the interactive role assignment, which need a person at a terminal. The renderer and prompts are covered only by tests of their output.

📝 Checklist

• All new/changed/fixed functionality is covered by tests (or N/A)
• I have added documentation for all new/changed functionality (or N/A)

Diagrams

Tan is the cobra layer, blue is the domain package, purple is the Management API side, gray is test support.

%%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#eef6f7', 'primaryTextColor': '#2f3a3d', 'primaryBorderColor': '#b8d8dd', 'lineColor': '#7f9ea6', 'background': '#ffffff' } } }%%
flowchart LR
    subgraph CLI["internal/cli"]
        Setup["setup command"]
        Audit["audit command"]
        Adapters["tenant adapters"]
        DryRun["dry-run transport"]
        Terminal["terminal and prompter"]
    end
    subgraph Domain["internal/portals"]
        Run["setup and business setup"]
        Rules["24 audit rules and fixes"]
        Stores["12 store interfaces"]
        UI["Reporter and Prompter interfaces"]
    end
    subgraph Remote["Management API"]
        SDK["go-auth0 v1 and v3"]
        Raw["raw requests: portals, forms, probes"]
    end
    subgraph Support["test support"]
        Fake[("portalstest fake tenant")]
    end
    Setup --> Run
    Audit --> Rules
    Run --> Stores
    Rules --> Stores
    Run --> UI
    Terminal -.implements.-> UI
    Adapters -.implements.-> Stores
    Adapters --> SDK
    Adapters --> Raw
    DryRun -.wraps.-> SDK
    DryRun -.wraps.-> Raw
    Fake -.implements.-> Stores
    classDef entry fill:#f7efe5,stroke:#d8b98f,color:#2f3a3d
    classDef domain fill:#e8f4f8,stroke:#a8d4e6,color:#2f3a3d
    classDef remote fill:#f6eff9,stroke:#cfb5dc,color:#2f3a3d
    classDef support fill:#f3f3f3,stroke:#cfcfcf,color:#2f3a3d
    class Setup,Audit,Adapters,DryRun,Terminal entry
    class Run,Rules,Stores,UI domain
    class SDK,Raw remote
    class Fake support
    style CLI fill:#fdfaf5,stroke:#d8b98f
    style Domain fill:#f4fafc,stroke:#a8d4e6
    style Remote fill:#fbf8fc,stroke:#cfb5dc
    style Support fill:#fafafa,stroke:#cfcfcf

Loading

The domain package depends only on interfaces. The same flow runs against the real tenant, the dry-run transport, or the fake tenant, depending on what is plugged into the stores.

%%{init: { 'sequence': {'mirrorActors':false}, 'theme': 'base', 'themeVariables': { 'primaryColor': '#eef6f7', 'primaryTextColor': '#2f3a3d', 'primaryBorderColor': '#b8d8dd', 'lineColor': '#7f9ea6', 'background': '#ffffff', 'actorBkg': '#f7efe5', 'actorBorder': '#d8b98f', 'actorTextColor': '#2f3a3d', 'noteBkgColor': '#fff8d8', 'noteTextColor': '#2f3a3d', 'noteBorderColor': '#e7d28a' } } }%%
sequenceDiagram
    actor User
    box rgb(247,239,229) CLI layer
        participant Cmd as setup command
        participant Ad as tenant adapters
    end
    box rgb(232,244,248) Domain
        participant Pf as preflight
        participant Su as setup
    end
    box rgb(246,239,249) Management API
        participant API as tenant
    end
    User->>Cmd: setup --template consumer --name ...
    Cmd->>Su: run(stores, reporter, prompter)
    Su->>Pf: check permissions
    Pf->>Ad: probes, 4 at a time
    Ad->>API: requests that are rejected or empty
    API-->>Pf: 400 ok or 403 missing scope
    Pf-->>Su: ready, or MissingScopes with advice
    Su->>Ad: find or create app, grants, vault, forms, portal
    Ad->>API: GET and POST
    Su-->>Cmd: resources with created or reused status
    Cmd-->>User: summary, or the JSON result

Loading

With --dry-run the adapters are built on the recording transport: the GETs above go to the tenant, and the POSTs are kept with placeholder ids instead of sent.

🤖 Generated with Claude Code