# AUTH0_KEYWORD_REPLACE_MAPPINGS: Dynamic Configuration Management in Auth0 Deploy CLI

> Master AUTH0_KEYWORD_REPLACE_MAPPINGS for Auth0 Deploy CLI dynamic configuration. Create environment-agnostic files easily for seamless deployments without code changes.

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

---

**AUTH0_KEYWORD_REPLACE_MAPPINGS is a configuration object that drives runtime keyword replacement throughout the Deploy CLI's import and export workflows, enabling environment-agnostic configuration files that adapt to different deployment targets without code changes.**

In the `auth0/auth0-deploy-cli` repository, `AUTH0_KEYWORD_REPLACE_MAPPINGS` serves as the central mechanism for injecting environment-specific values into Auth0 resource configurations. This feature allows development teams to maintain a single source of truth for their Auth0 setup while seamlessly deploying to development, staging, and production environments.

## What is AUTH0_KEYWORD_REPLACE_MAPPINGS?

`AUTH0_KEYWORD_REPLACE_MAPPINGS` is defined in [`src/types.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/types.ts) as an optional configuration field that accepts a `KeywordMappings` object. This object maps placeholder keys to concrete values—strings, numbers, arrays, or objects—that replace special markers in your configuration files during the import and export processes.

The mappings enable **multi-environment workflows** where the same YAML or directory-based configuration files can be reused across different Auth0 tenants by simply changing the mapping object in your [`config.json`](https://github.com/auth0/auth0-deploy-cli/blob/main/config.json) or through environment variables.

## How AUTH0_KEYWORD_REPLACE_MAPPINGS Works

The keyword replacement pipeline operates across several core components of the Deploy CLI, transforming placeholder markers into actual values at runtime.

### Configuration Loading

When the CLI initializes, it loads the configuration file and extracts the mappings into context objects. In [`src/context/yaml/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/yaml/index.ts), the constructor captures these mappings:

```typescript
// src/context/yaml/index.ts
this.mappings = config.AUTH0_KEYWORD_REPLACE_MAPPINGS || {};

```

The same pattern occurs in [`src/context/directory/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/directory/index.ts), ensuring both YAML and directory formats have access to the replacement mappings.

### File Processing and Replacement

During asset loading, the CLI reads configuration files and processes them through `loadFileAndReplaceKeywords` in [`src/tools/utils.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/utils.ts):

```typescript
// src/tools/utils.ts
if (mappings && !disableKeywordReplacement) {
    return keywordReplace(fs.readFileSync(f, 'utf8'), mappings);
}

```

The `keywordReplace` function orchestrates the transformation by first processing array markers via `keywordArrayReplace`, then handling string substitution through `keywordStringReplace`. This two-phase approach ensures complex data structures are properly serialized before literal string replacement occurs.

### Export Preservation

When `AUTH0_PRESERVE_KEYWORDS=true`, the CLI protects existing markers during export operations. The system loads local files with `disableKeywordReplacement: true` to retain raw markers, then executes `preserveKeywords` from [`src/keywordPreservation.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/keywordPreservation.ts) to merge remote values while maintaining the original placeholder syntax.

## Syntax and Marker Styles

The Deploy CLI supports two distinct marker styles that control how values are injected into configuration files.

### JSON-Stringified Markers (`@@KEY@@`)

Using double at-signs triggers JSON serialization of the mapped value. This is essential when the target field expects arrays or objects:

```yaml
tenant:
  allowed_logout_urls: "@@ALLOWED_LOGOUT_URLS@@"

```

If `ALLOWED_LOGOUT_URLS` maps to `["https://app.com/logout", "http://localhost:3000/logout"]`, the result becomes a proper YAML array.

### Literal String Markers (`##KEY##`)

Double hash marks perform literal substitution without JSON serialization, ideal for simple string values:

```yaml
tenant:
  friendly_name: "##ENVIRONMENT## tenant"

```

If `ENVIRONMENT` equals `"production"`, the output is `friendly_name: "production tenant"` without extra quotes.

## Practical Implementation Examples

### Basic Configuration Setup

Define your mappings in [`config.json`](https://github.com/auth0/auth0-deploy-cli/blob/main/config.json):

```json
{
  "AUTH0_DOMAIN": "my-tenant.us.auth0.com",
  "AUTH0_CLIENT_ID": "ABC123",
  "AUTH0_CLIENT_SECRET": "secret",
  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
    "ENVIRONMENT": "prod",
    "ALLOWED_LOGOUT_URLS": [
      "https://my-prod-app.com/logout",
      "http://localhost:3000/logout"
    ],
    "API_AUDIENCE": "https://api.my-prod-app.com"
  }
}

```

### YAML Template Usage

Create environment-agnostic YAML files:

```yaml
tenant:
  friendly_name: "##ENVIRONMENT## tenant"

  allowed_logout_urls: "@@ALLOWED_LOGOUT_URLS@@"
  default_audience: "##API_AUDIENCE##"

```

During import, the CLI transforms this to:

```yaml
tenant:
  friendly_name: "prod tenant"
  allowed_logout_urls:
    - "https://my-prod-app.com/logout"
    - "http://localhost:3000/logout"
  default_audience: "https://api.my-prod-app.com"

```

### Programmatic Usage

You can also use the replacement utilities directly:

```typescript
import { keywordReplace } from './src/tools/utils';
import { KeywordMappings } from './src/types';

const mappings: KeywordMappings = {
  DOMAIN: 'my-tenant.us.auth0.com',
  ENV: 'stage'
};

const raw = 'https://@@DOMAIN@@/api/##ENV##';
const result = keywordReplace(raw, mappings);
// result => 'https://my-tenant.us.auth0.com/api/stage'

```

## Summary

- **AUTH0_KEYWORD_REPLACE_MAPPINGS** enables runtime substitution of placeholders in Auth0 configuration files, supporting multi-environment deployments from a single codebase.

- The system uses two marker styles: `@@KEY@@` for JSON-stringified values (arrays/objects) and `##KEY##` for literal string substitution.

- Core implementation resides in [`src/tools/utils.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/utils.ts) (`keywordReplace`, `keywordStringReplace`, `keywordArrayReplace`) and is consumed by context 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).

- The `AUTH0_PRESERVE_KEYWORDS` feature leverages [`src/keywordPreservation.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/keywordPreservation.ts) to maintain placeholder markers during export operations, preventing configuration drift.

- Mappings can be defined in [`config.json`](https://github.com/auth0/auth0-deploy-cli/blob/main/config.json) or injected via environment variables for CI/CD pipelines.

## Frequently Asked Questions

### What happens if AUTH0_KEYWORD_REPLACE_MAPPINGS is not defined?

If the configuration object is omitted or empty, the CLI operates without keyword replacement. Files are processed as-is, and any `@@` or `##` markers remain in the literal text sent to Auth0, which typically causes validation errors or unintended string values in your tenant configuration.

### Can I use AUTH0_KEYWORD_REPLACE_MAPPINGS with environment variables?

Yes. According to the documentation in [`docs/keyword-replacement.md`](https://github.com/auth0/auth0-deploy-cli/blob/main/docs/keyword-replacement.md), the CLI automatically populates the mappings object from environment variables, allowing CI pipelines to inject secrets and environment-specific values without hard-coding them in [`config.json`](https://github.com/auth0/auth0-deploy-cli/blob/main/config.json). This supports secure, automated deployments across multiple environments.

### What is the difference between @@KEY@@ and ##KEY## markers?

The `@@KEY@@` syntax performs JSON-stringified replacement, meaning string values receive quotes and arrays/objects are properly formatted for YAML/JSON insertion. The `##KEY##` syntax performs literal substitution without JSON serialization, making it ideal for embedding simple strings into configuration values where additional quoting would break the syntax.

### How does AUTH0_PRESERVE_KEYWORDS protect my local configuration?

When `AUTH0_PRESERVE_KEYWORDS=true`, the CLI loads local files with keyword replacement disabled to retain raw markers, then executes the `preserveKeywords` function from [`src/keywordPreservation.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/keywordPreservation.ts) to merge remote values while keeping the original placeholders intact. This ensures that exported configurations maintain their templated structure for future deployments rather than being overwritten with environment-specific values.