Overlay commands

Commands for customizing third-party packs without forking. Available in all modes.

`aligntrue override add`

Create a new overlay to customize rules without forking.

Usage:


aligntrue override add [options]

Options:

Flag	Description	Required
`--selector <string>`	Selector string (rule[id=…], property.path, array[0])	Yes
`--set <key=value>`	Set property (repeatable, supports dot notation)	No*
`--remove <key>`	Remove property (repeatable)	No*
`--config <path>`	Custom config file path	No

*At least one of --set or --remove is required

What it does:

Validates selector syntax
Parses set/remove operations
Adds overlay to overlays.overrides[] in config
Writes config atomically
Provides next steps (run aligntrue sync)

Examples:


# Change severity for specific rule
aligntrue override add \
  --selector 'rule[id=no-console-log]' \
  --set severity=error
 
# Set nested property with dot notation
aligntrue override add \
  --selector 'rule[id=max-complexity]' \
  --set check.inputs.threshold=15
 
# Remove property
aligntrue override add \
  --selector 'rule[id=prefer-const]' \
  --remove autofix
 
# Multiple set operations
aligntrue override add \
  --selector 'rule[id=line-length]' \
  --set severity=warning \
  --set check.inputs.maxLength=120
 
# Combined set and remove
aligntrue override add \
  --selector 'rule[id=complexity]' \
  --set check.inputs.threshold=15 \
  --remove autofix

Output:


✓ Overlay added to config

Selector: rule[id=no-console-log]
  Set: severity=error

Next step:
  Run: aligntrue sync

Exit codes:

0 - Success
1 - Validation error (invalid selector, missing operations)
2 - System error (file write failed)

See also: Overlays Guide for complete overlay documentation.

`aligntrue override status`

View dashboard of all overlays with health status.

Usage:


aligntrue override status [options]

Options:

Flag	Description	Default
`--json`	Output in JSON format	`false`
`--config <path>`	Custom config file path	(default)

What it shows:

Overlay count (total, healthy, stale)
Selector for each overlay
Operations (set, remove)
Health status (healthy if selector matches, stale if no match)

Examples:


# Show all overlays
aligntrue override status
 
# JSON output for scripting
aligntrue override status --json

Example output:


Overlays (3 active, 1 stale)

✓ rule[id=no-console-log]
  Set: severity=error
  Healthy: yes

✓ rule[id=max-complexity]
  Set: check.inputs.threshold=15
  Healthy: yes

❌ rule[id=old-rule-name]
  Set: severity=off
  Healthy: stale (no match in IR)

JSON output:


{
  "total": 3,
  "healthy": 2,
  "stale": 1,
  "overlays": [
    {
      "selector": "rule[id=no-console-log]",
      "health": "healthy",
      "operations": {
        "set": { "severity": "error" }
      }
    }
  ]
}

Health indicators:

✓ Healthy - Overlay selector matches rules in IR
❌ Stale - Selector matches no rules

Exit codes:

0 - Success
1 - Config not found

See also: Drift Detection for automated staleness checks.

`aligntrue override diff`

Show the effect of overlays on IR.

Usage:


aligntrue override diff [selector] [options]

Arguments:

selector - Optional selector to filter (shows all if omitted)

Options:

Flag	Description	Default
`--config <path>`	Custom config file path	(default)

What it shows:

Original IR - IR before overlays applied
Modified IR - IR after overlays applied
Changes - Summary of modifications

Examples:


# Show all overlay effects
aligntrue override diff
 
# Show effect of specific overlay
aligntrue override diff 'rule[id=no-console-log]'

Example output:


Overlay diff for: rule[id=no-console-log]

━━━ Original (upstream) ━━━
severity: warn

━━━ With overlay ━━━
severity: error

Changes: 1 property modified

No overlay case:


No overlays match selector: rule[id=nonexistent]

Exit codes:

0 - Success
1 - Selector invalid or no overlays found

See also: Overlays Guide for overlay usage.

`aligntrue override remove`

Remove an overlay.

Usage:


aligntrue override remove [selector] [options]

Arguments:

selector - Optional selector string (if omitted, interactive mode)

Options:

Flag	Description	Default
`--force`	Skip confirmation	`false`
`--config <path>`	Custom config file path	(default)

What it does:

If no selector: shows interactive list of overlays
Finds matching overlay by selector
Prompts for confirmation (unless --force)
Removes overlay from config
Writes config atomically

Examples:


# Interactive removal (select from list)
aligntrue override remove
 
# Remove by selector
aligntrue override remove 'rule[id=no-console-log]'
 
# Remove without confirmation
aligntrue override remove 'rule[id=no-console-log]' --force

Interactive mode:


? Select overlay to remove
  > rule[id=no-console-log] (Set: severity=error)
    rule[id=max-complexity] (Set: check.inputs.threshold=15)
    rule[id=old-rule] (Set: severity=off)

Remove overlay: rule[id=no-console-log]? (y/N): y

✓ Overlay removed

Next step:
  Run: aligntrue sync

Exit codes:

0 - Success
1 - No matching overlay found

See also: Overlays Guide