How to Exclude Specific Resource Types Using AUTH0_EXCLUDED in Auth0 Deploy CLI

The AUTH0_EXCLUDED configuration property filters resource handlers at startup in the Auth0 Deploy CLI, preventing specified asset types from being processed during both import and export operations.

The Auth0 Deploy CLI provides granular control over which tenant resources are managed through the AUTH0_EXCLUDED configuration option. By specifying resource types in this array, you can completely bypass handlers for assets like clients, connections, or rules according to the source code in auth0/auth0-deploy-cli. This exclusion occurs during the initialization of the Auth0 class, ensuring excluded types never trigger Management API calls.

How AUTH0_EXCLUDED Filters Resource Handlers

When the CLI initializes, the Auth0 class constructor invokes config('AUTH0_EXCLUDED') to retrieve the exclusion list. According to the implementation in src/tools/auth0/index.ts (lines 57-62), the CLI filters the this.handlers array by checking each handler's type against the exclusion list:

// src/tools/auth0/index.ts – handler filtering
const excludedAssetTypes: undefined | AssetTypes[] = config('AUTH0_EXCLUDED');

if (excludedAssetTypes === undefined) return true;

return !excludedAssetTypes.includes(handler.type as AssetTypes);

If a handler's type appears in AUTH0_EXCLUDED, it is removed from the active handlers array. Only the remaining handlers participate in the three-stage pipeline: load, validate, and processChanges. This mechanism operates bidirectionally—excluded types are ignored during both export operations (reading from Auth0) and import operations (writing to Auth0).

Because this filtering occurs before any network requests, the CLI avoids rate-limit pressure on large tenants and completes deployments faster by skipping unnecessary Management API endpoints.

Supported Resource Types

The list of valid resource names corresponds to the AssetTypes enum defined in src/types.ts (lines 65-70). These values represent the exact strings you must use in your AUTH0_EXCLUDED array.

Comprehensive documentation of supported resource types is maintained in docs/excluding-from-management.md. This file enumerates all manageable assets, from clients and connections to organizations and databases, ensuring you use the correct identifiers recognized by the CLI's configuration validator.

Configuring AUTH0_EXCLUDED

You can supply the AUTH0_EXCLUDED array through environment variables or configuration files. The src/configFactory.ts module resolves these values and passes them to the Auth0 constructor.

Using a JSON or YAML Configuration File

Define the exclusion list in your config file passed via the -c or --config flag:

{
  "AUTH0_DOMAIN": "my-tenant.auth0.com",
  "AUTH0_CLIENT_ID": "YOUR_CLIENT_ID",
  "AUTH0_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
  "AUTH0_EXCLUDED": ["clients", "connections", "databases", "organizations"]
}

Execute the CLI with this configuration:

node lib/index.js export -c ./config.json -f directory -o ./exported

The CLI skips the clients, connections, databases, and organizations handlers for both export and subsequent import operations.

Using Environment Variables

Set the environment variable before running the CLI command:

export AUTH0_EXCLUDED='["rules","actions"]'
node lib/index.js import -c ./config.json -i ./exported/tenant.yaml

This omits only the rules and actions handlers while processing all other resource types normally.

Validation and Mutual Exclusion Constraints

The CLI enforces strict validation in src/context/index.ts (lines 69-76) to prevent conflicting exclusion directives. You cannot define both AUTH0_EXCLUDED and AUTH0_INCLUDED_ONLY simultaneously; the configuration validator throws an error if both properties are present.

Additionally, distinguish AUTH0_EXCLUDED from resource-specific exclusion variables like AUTH0_EXCLUDED_CLIENTS. The latter excludes individual resources by name or ID but does not disable the entire resource type handler. AUTH0_EXCLUDED operates at the type level, while AUTH0_EXCLUDED_<RESOURCE> operates at the instance level.

Debugging Active Handlers

To verify which handlers remain active after applying exclusions, enable debug logging:

export AUTH0_DEBUG=true
node lib/index.js export -c ./config.json -f yaml -o ./out

The debug output prints the final this.handlers array, confirming that excluded types are not present and will not generate Management API traffic.

Summary

• Bidirectional exclusion: AUTH0_EXCLUDED prevents processing during both import and export operations by filtering handlers in src/tools/auth0/index.ts.
• Configuration methods: Supply exclusions via JSON/YAML config files or the AUTH0_EXCLUDED environment variable, resolved by src/configFactory.ts.
• Type-level filtering: Exclusions apply to entire resource types (e.g., "clients", "connections"), not individual instances.
• Mutual exclusivity: Cannot be used simultaneously with AUTH0_INCLUDED_ONLY; validation logic in src/context/index.ts enforces this constraint.
• Performance benefit: Excluded types trigger zero Management API calls, reducing deployment time and rate-limit consumption.

Frequently Asked Questions

What is the difference between AUTH0_EXCLUDED and AUTH0_INCLUDED_ONLY?

AUTH0_EXCLUDED removes specific resource types from processing while keeping all others active, whereas AUTH0_INCLUDED_ONLY removes everything except the specified types. The CLI validates in src/context/index.ts that you only use one of these mutually exclusive options at a time to prevent ambiguous configuration.

Can I use AUTH0_EXCLUDED to exclude individual resources by ID?

No. AUTH0_EXCLUDED operates at the resource type level, disabling entire handlers for categories like clients or rules. To exclude individual resources by name or ID, use the corresponding AUTH0_EXCLUDED_<RESOURCE> variable (e.g., AUTH0_EXCLUDED_CLIENTS), which filters specific instances after the handler loads the data.

Does AUTH0_EXCLUDED work for both import and export operations?

Yes. Because the exclusion logic in src/tools/auth0/index.ts filters the this.handlers array during initialization—before the load, validate, or processChanges stages execute—the specified types are ignored bidirectionally. The CLI neither reads these resources from Auth0 during export nor attempts to create or update them during import.

Where can I find the list of valid resource types for AUTH0_EXCLUDED?

The complete enumeration of valid AssetTypes values is documented in docs/excluding-from-management.md and formally defined in src/types.ts. These strings correspond exactly to the handler type identifiers used internally by the CLI, ensuring your exclusion configuration matches the expected schema.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}