# How the AUTH0_INCLUDED_ONLY Option Restricts Deployments in Auth0-Deploy-CLI

> Learn how AUTH0_INCLUDED_ONLY restricts Auth0 Deploy CLI deployments to only specified resources. This whitelist option ensures precise control over your deployments, ignoring all other assets.

- Repository: [Auth0/auth0-deploy-cli](https://github.com/auth0/auth0-deploy-cli)
- Tags: how-to-guide
- Published: 2026-02-25

---

**The AUTH0_INCLUDED_ONLY configuration option acts as a whitelist that restricts the Auth0 Deploy CLI to process only explicitly listed resource types during both import and export operations, ignoring all other assets.**

The `AUTH0_INCLUDED_ONLY` option in the `auth0/auth0-deploy-cli` repository provides a precise mechanism for limiting deployment scope to specific Auth0 resource types. This configuration flag ensures that only explicitly listed assets—such as clients, connections, or tenant settings—are processed during import and export operations, while all other resources are systematically excluded from the deployment lifecycle.

## Understanding the AUTH0_INCLUDED_ONLY Configuration Option

The `AUTH0_INCLUDED_ONLY` option accepts an array of resource type strings that define exactly which handlers the Deploy CLI should execute. When this option is defined, the CLI enters a whitelist mode where any resource type not explicitly included in the array is treated as excluded. This behavior applies symmetrically to both loading local assets into Auth0 (import) and dumping Auth0 configurations to local files (export).

## How AUTH0_INCLUDED_ONLY Works Under the Hood

The implementation of `AUTH0_INCLUDED_ONLY` spans multiple layers of the CLI architecture, from initial configuration validation through final asset processing.

### Configuration Validation in src/context/index.ts

Before any deployment operations begin, the CLI validates the `AUTH0_INCLUDED_ONLY` configuration in [`src/context/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/index.ts). The validation ensures the array is not empty and enforces mutual exclusivity with `AUTH0_EXCLUDED`, preventing ambiguous configuration states.

```typescript
if (config.AUTH0_INCLUDED_ONLY.length === 0) {
  throw new Error('Need to define at least one resource type …');
}
if (hasExcludedResources && hasIncludedResources) {
  throw new Error('Both AUTH0_EXCLUDED and AUTH0_INCLUDED_ONLY …');
}

```

### Filtering Local Assets During Import

When loading local assets from YAML or directory structures, the CLI applies the inclusion filter to determine which handlers to invoke. In [`src/context/yaml/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/yaml/index.ts) and [`src/context/directory/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/directory/index.ts), the `filterOnlyIncludedResourceTypes` function intercepts the handler list before asset parsing begins.

```typescript
Object.entries(handlers)
  .filter(([handlerName]) => !excludedAssetTypes.includes(handlerName))
  .filter(filterOnlyIncludedResourceTypes(this.config.AUTH0_INCLUDED_ONLY))
  .forEach(([_, handler]) => { … });

```

If a resource type is not present in the `AUTH0_INCLUDED_ONLY` array, its handler is never invoked, ensuring the asset never enters the in-memory `assets` object.

### Restricting Export Operations

During export operations, the same filtering logic applies when dumping Auth0 configurations to local files. The CLI iterates over handlers in [`src/context/yaml/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/yaml/index.ts) and [`src/context/directory/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/directory/index.ts), skipping any resource types not explicitly included.

```typescript
Object.entries(handlers)
  .filter(([handlerName]) => !excludedAssetTypes.includes(handlerName))
  .filter(filterOnlyIncludedResourceTypes(this.config.AUTH0_INCLUDED_ONLY))
  .map(async ([name, handler]) => { … });

```

### The filterOnlyIncludedResourceTypes Utility

The core filtering logic resides in [`src/context/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/index.ts) as a higher-order function that returns `true` for every handler when `AUTH0_INCLUDED_ONLY` is undefined, otherwise checking membership in the included array.

```typescript
export const filterOnlyIncludedResourceTypes = (includedAssetTypes) => ([handlerName]) => {
  if (includedAssetTypes === undefined) return true;
  return includedAssetTypes.includes(handlerName);
};

```

## Practical Implementation Examples

### Basic Configuration

To restrict deployments to specific resource types, define the `AUTH0_INCLUDED_ONLY` array in your configuration file:

```json
{
  "AUTH0_DOMAIN": "my-tenant.auth0.com",
  "AUTH0_CLIENT_ID": "...",
  "AUTH0_CLIENT_SECRET": "...",
  "AUTH0_INPUT_FILE": "./local/",
  "AUTH0_INCLUDED_ONLY": ["clients", "connections", "tenant"]
}

```

This configuration ensures only `clients`, `connections`, and `tenant` assets are processed during import or export operations.

### Running Import and Export Commands

Execute the CLI with the restricted configuration:

```bash

# Export only the whitelisted types

npm run build && node lib/index.js export -c config.json -f yaml -o ./exported/

```

The CLI performs three validation steps:

1. Verifies `AUTH0_INCLUDED_ONLY` is non-empty (validation in [`src/context/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/index.ts))
2. Filters handlers using `filterOnlyIncludedResourceTypes` to exclude non-listed resource types
3. Generates output containing only the specified sections

### Error Handling for Invalid Configurations

Attempting to use both exclusion and inclusion flags simultaneously results in an immediate error:

```json
{
  "AUTH0_EXCLUDED": ["rules"],
  "AUTH0_INCLUDED_ONLY": ["clients"]
}

```

The CLI aborts with the message:

```

Both AUTH0_EXCLUDED and AUTH0_INCLUDED_ONLY configuration values are defined, only one can be configured at a time.

```

This validation occurs in [`src/context/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/index.ts) before any deployment operations begin.

## Summary

- **AUTH0_INCLUDED_ONLY** acts as a whitelist that restricts the Auth0 Deploy CLI to process only explicitly listed resource types.
- The option is validated in [`src/context/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/index.ts) to ensure it is non-empty and mutually exclusive with `AUTH0_EXCLUDED`.
- During import operations, the CLI filters handlers in [`src/context/yaml/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/yaml/index.ts) and [`src/context/directory/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/directory/index.ts) to load only included assets.
- During export operations, the same filtering logic ensures only specified resource types are written to output files.
- The `filterOnlyIncludedResourceTypes` utility function in [`src/context/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/index.ts) provides the core filtering mechanism, returning `true` for all handlers when the option is undefined.

## Frequently Asked Questions

### What happens if AUTH0_INCLUDED_ONLY is undefined?

When `AUTH0_INCLUDED_ONLY` is undefined, the `filterOnlyIncludedResourceTypes` utility returns `true` for every handler, allowing the CLI to process all resource types. This maintains backward compatibility and default behavior where no restrictions are applied.

### Can I use AUTH0_INCLUDED_ONLY with AUTH0_EXCLUDED?

No, these options are mutually exclusive. The CLI validates this constraint in [`src/context/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/index.ts) and throws an error if both are defined simultaneously. This prevents ambiguous configuration states where a resource type might appear in both lists.

### Which resource types can I include in AUTH0_INCLUDED_ONLY?

You can include any valid Auth0 resource type that the Deploy CLI supports, such as `clients`, `connections`, `tenant`, `rules`, `hooks`, `resourceServers`, `clientGrants`, `guardian`, `roles`, `users`, `organizations`, and `actions`. The specific available types depend on your CLI version and Auth0 tenant configuration.

### Does AUTH0_INCLUDED_ONLY affect both import and export operations?

Yes, the option applies bi-directionally. During import (deploy), the CLI filters which handlers load local assets into Auth0. During export (dump), the same filter restricts which resource types are written to local files. This ensures consistent behavior regardless of operation direction.