# How to Use EXCLUDED_PROPS and INCLUDED_PROPS for Property-Level Filtering in Auth0 Deploy CLI

> Master Auth0 property level filtering with EXCLUDED_PROPS and INCLUDED_PROPS in auth0-deploy-cli. Streamline tenant configuration exports and imports effectively.

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

---

**Use `EXCLUDED_PROPS` to strip specific properties from exported Auth0 tenant configurations and `INCLUDED_PROPS` to retain fields that would otherwise be removed by the CLI's default read-only field list, configuring both as resource-keyed maps in your JSON or YAML configuration file.**

The `auth0/auth0-deploy-cli` repository provides granular control over infrastructure-as-code workflows through property-level filtering capabilities. By configuring `EXCLUDED_PROPS` and `INCLUDED_PROPS` in your configuration file, you can selectively remove sensitive data or unnecessary fields from exports while preserving secrets that the tool would normally strip automatically. These settings merge with built-in read-only field definitions in [`src/readonly.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/readonly.ts) to customize exactly what gets written to your local configuration files.

## Understanding EXCLUDED_PROPS and INCLUDED_PROPS

`EXCLUDED_PROPS` and `INCLUDED_PROPS` are configuration options that filter individual properties of Auth0 resources during dump and import operations. Both accept an object where keys are resource types (such as `clients` or `connections`) and values are arrays of property names.

| Option | Type | Purpose |
|--------|------|---------|
| **EXCLUDED_PROPS** | `{ [resource: string]: string[] }` | Lists properties that must always be removed from the exported definition of the specified resource. |
| **INCLUDED_PROPS** | `{ [resource: string]: string[] }` | Lists properties that should be kept even if they appear in the default read-only list, effectively overriding the built-in exclusions. |

The CLI maintains a default list of read-only fields—including `client_secret`, `callback_url_template`, and others—that are normally stripped to prevent secrets from leaking into version control. `INCLUDED_PROPS` acts as the inverse mechanism to re-add specific fields when you need them in your exported assets.

## Core Implementation in src/readonly.ts

The merging logic lives in the `getExcludedFields` function within **[`src/readonly.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/readonly.ts)**. This function combines your custom filters with the default `readOnlyFields` map:

```typescript
// src/readonly.ts
function getExcludedFields(config: Config) {
  const strippedFields = { ...readOnlyFields };
  let { EXCLUDED_PROPS: excluded, INCLUDED_PROPS: included } = config;
  
  // Add user-provided excluded fields
  strippedFields[name] = (strippedFields[name] || []).concat(fields);
  
  // Remove any fields that the user explicitly included
  strippedFields[name] = strippedFields[name].filter(
    (field: string) => !fields.includes(field)
  );
}

```

The function validates that no property appears simultaneously in both maps. If `getExcludedFields` detects an intersection, the CLI throws a validation error:

```typescript
if (intersections.length > 0) {
  throw new Error(
    `EXCLUDED_PROPS should NOT have any intersections with INCLUDED_PROPS. Intersections found: ${name}: ${intersections.join(', ')}`);
}

```

## Configuration Examples

### JSON Configuration Format

Define your filters in a JSON configuration file to strip custom login pages from clients and IDP-initiated settings from connections, while forcing the retention of client secrets:

```json
{
  "AUTH0_DOMAIN": "mytenant.auth0.com",
  "AUTH0_CLIENT_ID": "xxxx",
  "AUTH0_CLIENT_SECRET": "yyyy",
  "EXCLUDED_PROPS": {
    "clients": [
      "client_secret",
      "custom_login_page"
    ],
    "connections": [
      "options.idp_initiated"
    ]
  },
  "INCLUDED_PROPS": {
    "clients": [
      "client_secret"
    ]
  }
}

```

### YAML Configuration Format

The same filtering rules work in YAML syntax:

```yaml
AUTH0_DOMAIN: mytenant.auth0.com
AUTH0_CLIENT_ID: xxxx
AUTH0_CLIENT_SECRET: yyyy
EXCLUDED_PROPS:
  clients:
    - custom_login_page
  connections:
    - options.idp_initiated
INCLUDED_PROPS:
  clients:
    - client_secret

```

### Running the CLI with Property Filters

Execute the export command referencing your configuration file to apply the property-level filters:

```bash

# Export tenant configuration while applying the filters above

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

```

The resulting YAML or JSON files will **not contain** `clients.custom_login_page` or `connections.options.idp_initiated`. However, `client_secret` **will remain present** in the output because `INCLUDED_PROPS` overrides the default exclusion.

## When Filtering Is Applied

During **export**, the `cleanAssets` function (also in [`src/readonly.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/readonly.ts)) uses the calculated `excludedFields` to sanitize resources before writing them to disk. This ensures sensitive or unnecessary data never reaches your local file system.

During **import**, specific handlers may reference these maps to preserve certain values. For example, the **connections** handler in **[`src/tools/auth0/handlers/connections.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/auth0/handlers/connections.ts)** checks `config()?.EXCLUDED_PROPS?.connections` to maintain excluded `options.*` values while updating connection configurations, preventing the import process from overwriting settings you intentionally left out of your configuration files.

## Summary

- **`EXCLUDED_PROPS`** removes specified properties from exported Auth0 resource definitions.
- **`INCLUDED_PROPS`** retains fields that would otherwise be stripped by the default read-only list in [`src/readonly.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/readonly.ts).
- The validation logic in `getExcludedFields` prevents conflicting configurations where a property appears in both lists simultaneously.
- Property filters apply during the export phase via `cleanAssets` and may be referenced by import handlers like the connections handler.
- Both options support dot notation for nested properties (for example, `options.idp_initiated`).

## Frequently Asked Questions

### What happens if I list the same property in both EXCLUDED_PROPS and INCLUDED_PROPS?

The CLI throws a validation error during configuration loading. The `getExcludedFields` function in [`src/readonly.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/readonly.ts) explicitly checks for intersections between the two maps and fails with a message listing the conflicting properties, ensuring you cannot simultaneously include and exclude the same field.

### Can I use dot notation to filter nested properties like options.idp_initiated?

Yes. The filtering mechanism supports dot notation for nested object paths. For example, configuring `"connections": ["options.idp_initiated"]` in `EXCLUDED_PROPS` targets specifically the `idp_initiated` key within the `options` object of connection definitions.

### Do these filters modify my actual Auth0 tenant or only the exported files?

These filters primarily affect the exported configuration files written to your local file system. During import operations, handlers like the one in [`src/tools/auth0/handlers/connections.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/auth0/handlers/connections.ts) may reference `EXCLUDED_PROPS` to determine which existing tenant properties should be preserved rather than overwritten, but the filters do not delete data directly from the Auth0 tenant itself.

### Where are the default read-only fields defined?

The default read-only field definitions reside in **[`src/readonly.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/readonly.ts)**. This file contains the base `readOnlyFields` map that specifies which sensitive properties (such as `client_secret` and `callback_url_template`) are automatically stripped from exports unless explicitly retained via `INCLUDED_PROPS`.