AUTH0_KEYWORD_REPLACE_MAPPINGS: Dynamic Configuration Management in Auth0 Deploy CLI

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 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 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, the constructor captures these mappings:

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

The same pattern occurs in 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:

// 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 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:

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:

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:

{
  "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:

tenant:
  friendly_name: "##ENVIRONMENT## tenant"

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

During import, the CLI transforms this to:

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:

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 (keywordReplace, keywordStringReplace, keywordArrayReplace) and is consumed by context handlers in src/context/yaml/index.ts and src/context/directory/index.ts.

• The AUTH0_PRESERVE_KEYWORDS feature leverages src/keywordPreservation.ts to maintain placeholder markers during export operations, preventing configuration drift.

• Mappings can be defined in 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, 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. 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 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.

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