cfgraft v0.4.0 was released on 15 November 2026. This release refocuses cfgraft as a pure CLI tool for safely syncing configuration from Git repositories, with portable home-relative paths, an XDG-compliant cache layout, and new validation and automation support. It is a breaking change for users who relied on the interactive terminal UI.

What’s new

cfgraft is now a non-interactive CLI only. The terminal UI and cfgraft tui subcommand have been removed, and the --interactive flag for sync is no longer supported. Configuration is edited directly in ~/.config/cfgraft/config.yaml.

Mapping targets can use portable home-relative paths. Targets may be absolute paths, ~/path, or "~" for the home directory itself. Resolution uses the current user’s home directory, or an absolute path stored in ~/.config/cfgraft/home if present, so the same config.yaml can be shared across machines with different home directories.

Repository caches have moved to ~/.cache/cfgraft/repos in line with XDG conventions. Config remains at ~/.config/cfgraft/config.yaml and state remains under ~/.config/cfgraft/state/.

The CLI gains practical workflow improvements. A new validate subcommand checks config structure and prints sources with resolved mappings without accessing repositories or writing files. Flags can be set via environment variables CFGRAFT_FORCE, CFGRAFT_DRY_RUN, and CFGRAFT_VERBOSE, with explicit flags taking precedence. Output uses terminal-aware color and respects NO_COLOR, and --verbose applies to both sync and diff. Help output now shows the config path and explains the YAML format.

Configuration handling is stricter. The YAML decoder rejects unknown fields and multiple documents, and targets are validated via resolveTarget with clear error context. Documentation has been refreshed with docs/CONFIG.md covering portable paths and home override, and docs/USAGE.md updated for the CLI-only workflow.

Why it matters

Removing the TUI makes cfgraft easier to automate in scripts and CI, and removes a dependency on interactive sessions. Portable home paths let teams share a single config file without hard-coding user-specific absolute paths, while the optional home override supports different machines cleanly.

Moving caches to ~/.cache keeps config directories lean and follows standard Linux conventions, making backups and cleanup more predictable. The validate command gives fast feedback before a sync, and environment defaults make repeated operations smoother in shell profiles or automation.

The changes trade interactive conflict resolution for explicit preview and control. Use --dry-run to preview changes and --force to overwrite, which aligns with Unix-style tooling expectations.

Upgrade

Download the release assets for darwin, linux, or windows from the GitHub release page and replace your existing binary. After upgrading, run:

cfgraft validate

to confirm your config is compatible, especially if you use home-relative targets. Then run:

cfgraft sync --dry-run

to verify mapping resolution and the new cache location at ~/.cache/cfgraft/repos. Old caches under ~/.config/cfgraft/repos are ignored and can be removed manually to free space.

Existing config.yaml files remain valid. Users previously using cfgraft tui should edit ~/.config/cfgraft/config.yaml directly, and any workflows relying on --interactive will need to switch to dry-run and force flags.

This post was AI-generated. The model used was unsloth/Muse-Glimmer-30B-GGUF:Muse-Glimmer-30B-UD-Q6_K_XL. Reference: repository UnitVectorY-Labs/cfgraft, release v0.4.0, published 2026-11-15. Date of generation: 2026-11-15. Author: release-storyteller.