How to Exclude Specific Rules, Clients, or Databases During Auth0 Deploy CLI Deployment

To exclude specific rules, clients, or databases during Auth0 Deploy CLI deployment, add the AUTH0_EXCLUDED array for global type exclusion or use AUTH0_EXCLUDED_RULES, AUTH0_EXCLUDED_CLIENTS, and AUTH0_EXCLUDED_DATABASES arrays for asset-by-name exclusion in your JSON configuration file.

The Auth0 Deploy CLI (auth0-deploy-cli) enables automated import and export of tenant configurations, but you often need to skip certain assets like legacy rules or production databases. According to the auth0/auth0-deploy-cli source code, the tool supports two complementary exclusion mechanisms controlled via the configuration file passed with the -c flag. These settings are interpreted during context initialization and enforced during the change-calculation phase.

How Exclusion Mechanisms Work

The CLI determines which assets to process by reading the configuration object during the local context building phase. In src/context/yaml/index.ts and src/context/directory/index.ts, the tool constructs exclusion arrays from your config:

rules: config.AUTH0_EXCLUDED_RULES || [],
clients: config.AUTH0_EXCLUDED_CLIENTS || [],
databases: config.AUTH0_EXCLUDED_DATABASES || [],
connections: config.AUTH0_EXCLUDED_CONNECTIONS || [],
resourceServers: config.AUTH0_EXCLUDED_RESOURCE_SERVERS || [],

During the change-calculation phase (src/tools/calculateChanges.ts), the context's excludedAssetTypes list is consulted first. If an asset type appears in this global exclusion list, it is completely omitted from both import and export operations. If the type is not globally excluded, individual handlers check their specific exclusion arrays.

Global Type Exclusion Using AUTH0_EXCLUDED

The global exclusion mechanism allows you to skip entire resource types. Set the AUTH0_EXCLUDED array in your configuration file to exclude all instances of specific asset types.

{
  "AUTH0_EXCLUDED": ["rules", "databases", "connections"]
}

This prevents the Deploy CLI from making any API calls to the specified endpoints. This approach is recommended over legacy specific exclusion keys, as noted in the deprecation warnings within src/context/index.ts.

Asset-by-Name Exclusion for Specific Assets

For granular control, exclude individual assets by their identifiers. Each resource type has a dedicated configuration key that accepts an array of names or IDs.

Excluding Specific Rules by ID

The rules handler in src/tools/auth0/handlers/rules.ts checks each rule's ID against the AUTH0_EXCLUDED_RULES array:

if (config.AUTH0_EXCLUDED_RULES?.includes(rule.id)) {
  // skip this rule
}

Configure your exclusion list using exact rule IDs:

{
  "AUTH0_EXCLUDED_RULES": [
    "rule_5a1b2c3d4e5f6g7h8i9j",
    "auth0-account-link-extension"
  ]
}

Excluding Specific Clients by Name

For clients, the handler checks against exact client names. In src/tools/auth0/handlers/clients.ts, the tool filters out any client whose name appears in AUTH0_EXCLUDED_CLIENTS:

{
  "AUTH0_EXCLUDED_CLIENTS": [
    "my-frontend-app",
    "service-worker-client"
  ]
}

Excluding Specific Databases by Name

Similarly, exclude specific database connections by name using AUTH0_EXCLUDED_DATABASES, which is processed in src/tools/auth0/handlers/databases.ts:

{
  "AUTH0_EXCLUDED_DATABASES": [
    "users-db-dev",
    "legacy-auth-db"
  ]
}

Critical Configuration Constraints

Deprecation Warning: The specific exclusion keys (AUTH0_EXCLUDED_RULES, AUTH0_EXCLUDED_CLIENTS, AUTH0_EXCLUDED_DATABASES, etc.) are deprecated in favor of the generic AUTH0_EXCLUDED list. While they remain functional for backward compatibility, the project recommends migrating to the global exclusion approach.

Validation Rule: You cannot mix global and asset-by-name exclusions for the same resource type. The validation logic in src/context/index.ts (lines 73-78) throws an error if you attempt to use both AUTH0_EXCLUDED (containing "clients") and AUTH0_EXCLUDED_CLIENTS simultaneously. Choose one mechanism per asset type.

Practical Configuration Examples

Combine global exclusions with asset-specific exclusions for different resource types:

{
  "AUTH0_EXCLUDED": ["connections"],
  "AUTH0_EXCLUDED_CLIENTS": ["admin-portal"]
}

Run the CLI with your configuration file using the -c flag:

node lib/index.js import -c my-config.json -i ./local/

The CLI automatically honors all exclusion settings during both import and export operations, leaving specified assets untouched.

Summary

• The Auth0 Deploy CLI supports two exclusion mechanisms: global type exclusion via AUTH0_EXCLUDED and asset-by-name exclusion via AUTH0_EXCLUDED_RULES, AUTH0_EXCLUDED_CLIENTS, and AUTH0_EXCLUDED_DATABASES.
• Global exclusions prevent all API calls for specified resource types, while name-based exclusions filter individual assets during handler processing in src/tools/auth0/handlers/.
• Specific exclusion keys are deprecated but remain functional; mixing them with global exclusions for the same type triggers validation errors in src/context/index.ts.
• Configuration is applied during context initialization in both src/context/yaml/index.ts and src/context/directory/index.ts, then enforced during change calculation.

Frequently Asked Questions

Can I exclude rules by name instead of ID?

While AUTH0_EXCLUDED_RULES primarily checks rule IDs as implemented in src/tools/auth0/handlers/rules.ts, some legacy configurations support rule names. However, IDs are the reliable identifier. For name-based exclusion of other assets like clients and databases, exact string matching against the name field is used.

What happens if I accidentally list a client in both AUTH0_EXCLUDED and AUTH0_EXCLUDED_CLIENTS?

The validation logic in src/context/index.ts prevents the CLI from running and throws a configuration error. You must choose either global type exclusion (listing "clients" in AUTH0_EXCLUDED) or specific asset exclusion (AUTH0_EXCLUDED_CLIENTS), but not both for the same resource type.

Do exclusions work for both import and export operations?

Yes. The exclusion settings apply symmetrically to both directions. During export, excluded assets are not written to your local directory. During import, the CLI skips API calls for excluded assets, leaving the tenant configuration for those resources untouched.

Where can I find the complete list of excludable resource types?

The TypeScript definitions in src/types.ts define the configuration interface including all exclusion fields. Additionally, the examples/yaml/config.json.example file demonstrates practical usage of exclusion keys for various resource types including connections, resourceServers, and defaults.

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