Syntax Reference (Advanced)

Technical reference for KDL structures used by declarch.

If you are new, read:

• Quick Start
• KDL Basics
• Backends

Core blocks

meta { ... }
imports { ... }
pkg { ... }

Package declarations

Preferred (nested)

pkg {
    pacman { firefox git }
    flatpak { org.mozilla.firefox }
    npm { typescript }
}

Also accepted (compatibility)

pkg:pacman { firefox git }

pkg {
    pacman:firefox
    npm:typescript
}

Optional advanced blocks

Backend options override

options:pacman {
    noconfirm_flag "--noconfirm"
}

Env override

env:global {
    "http_proxy=http://127.0.0.1:8080"
}

env:npm {
    "NPM_CONFIG_REGISTRY=https://registry.npmjs.org"
}

Package source overrides (backend-specific)

repos:pacman {
    "core"
    "extra"
}

Hooks

hooks {
    pre-sync "echo before"
    post-sync "echo after"
}

To execute hooks, users must opt in:

experimental {
    "enable-hooks"
}

And run sync with --hooks.

Policy

policy {
    protected "linux" "systemd"
    orphans "ask"
    require_backend "true"
    forbid_hooks "false"
    on_duplicate "warn"
    on_conflict "warn"
}

MCP policy (optional)

Default behavior is read-only for MCP actions. Enable write tools only when you explicitly trust your MCP client flow.

mcp {
    mode "write-enabled"
    allow_tools "declarch_sync_apply"
}

Profile and host blocks

These are optional overlays and are inactive by default.

profile "desktop" {
    pkg { aur { hyprland waybar } }
}

host "vps-1" {
    pkg { aur { fail2ban } }
}

Use from CLI:

• declarch sync --profile desktop
• declarch sync --host vps-1

Validation notes

• Keep beginner config in nested pkg style unless migration requires compatibility syntax.
• Unknown keys may be ignored in some contexts for forward compatibility.
• Use declarch lint --mode validate after manual edits.