Plugs commands

Manage dynamic configuration slots and fills in rule packs. Plugs allow template-based customization for stack-specific values.

`aligntrue plugs audit`

List all declared slots, current fills, and resolution status.

Usage:


aligntrue plugs audit [--config <path>]

Options:

Flag	Description	Default
`--config <path>`	Custom rules file path	`AGENTS.md`

What it shows:

Declared slots with descriptions, formats, and requirements
Current fill values for each slot
Resolution status (filled, required, optional)
Orphan fills (fills without declared slots)
Summary of required vs filled slots

Example output:


📌 Plugs Audit

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Slots declared:

  test.cmd
    Description: Command to run the project's tests
    Format:      command
    Required:    true
    Example:     pytest -q
    Status:      ✓ filled
    Fill:        pnpm test

  docs.url
    Description: Documentation website URL
    Format:      url
    Required:    false
    Example:     https://example.com/docs
    Status:      ○ optional

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Summary:
  Total slots:      2
  Required slots:   1
  Filled required:  1

Exit codes:

0 - Success
1 - Rules file not found or parsing error

See also: Plugs Guide for detailed plug usage

`aligntrue plugs resolve`

Preview plug resolution with current fills (dry-run mode).

Usage:


aligntrue plugs resolve [--config <path>] [--dry-run]

Options:

Flag	Description	Default
`--config <path>`	Custom rules file path	`AGENTS.md`
`--dry-run`	Preview without writing (default)	`true`

What it does:

Loads rules from config file
Resolves all [[plug:key]] references with current fills
Inserts TODO blocks for unresolved required plugs
Displays resolved text and unresolved plug list
Does NOT write changes (preview only)

Example output:


✓ Resolved 2 plugs

Resolved text preview:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Run tests with: pnpm test

Documentation: https://example.com/docs

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Unresolved required plugs: 0

With unresolved required plugs:


⚠ Unresolved required plugs: 1
  - author.name

Resolved text will contain TODO blocks:

TODO(plug:author.name): Provide a value for this plug.
Examples: John Doe

Exit codes:

0 - Success
1 - Rules file not found or parsing error

See also: Plugs Guide for resolution algorithm

`aligntrue plugs set`

Set a repo-local fill value with format validation.

Usage:


aligntrue plugs set <key> <value> [--config <path>]

Arguments:

key - Plug slot key (e.g., test.cmd, author.name)
value - Fill value (single-line string)

Options:

Flag	Description	Default
`--config <path>`	Custom rules file path	`AGENTS.md`

What it does:

Validates key exists as declared slot
Validates value matches slot format (command, text, file, url)
Writes fill to plugs.fills section in rules file
Preserves existing file structure and formatting

Format validation:

command - Single-line command, no environment variable interpolation (except CI=true)
text - Any single-line UTF-8 string
file - Repo-relative POSIX path, no .. segments, no absolute paths
url - Must start with http:// or https://

Examples:


# Set test command
aligntrue plugs set test.cmd "pnpm test"
 
# Set author name
aligntrue plugs set author.name "Jane Smith"
 
# Set documentation URL
aligntrue plugs set docs.url "https://docs.example.com"
 
# Set relative file path
aligntrue plugs set config.file "config/settings.json"

Example output:


✓ Set plug fill: test.cmd = "pnpm test"

Updated: AGENTS.md

Next step:
  Run: aligntrue sync

Exit codes:

0 - Success
1 - Validation error (invalid key, format mismatch, file not found)

Common errors:


✗ Slot not declared: unknown.key
  Hint: Run 'aligntrue plugs audit' to see declared slots

✗ Format validation failed: file
  Value contains '..' segments (not allowed)
  Hint: Use repo-relative paths without parent directory traversal

✗ Format validation failed: url
  Value must start with http:// or https://

See also: Plugs Guide for format requirements