XC manager

Version: 0.7.1

XC manager in Action

xc-manager-final.mp4

A high-performance, minimal dependency Zsh vault for managing complex commands.

[0.7.1] - 2026-03-31

Fixed

• Resolved an issue where placeholders ({{variable}}) were injected into the ZLE buffer without user input.
• Switched to a direct TTY read method to ensure interactive prompts work correctly within Zsh widgets.
• Improved trailing whitespace trimming for vault commands.

What's New in v0.7.0

Interactive Templating & Sync Engine

The v0.7.0 release transforms XC from a static command vault into a dynamic template engine.

Interactive Placeholders

You can now save commands with {{variables}}. When you execute a templated command, XC will intelligently prompt you for input.

• Smart Global Swap: If you use the same placeholder name multiple times (e.g., cp {{file}} {{file}}.bak), the engine only asks you once and updates all instances globally.
• Manual Control: Use different names (e.g., mv {{old}} {{new}}) to be prompted for each individual value.

Community "Package Manager"

The sync command has been completely redesigned.

• xc sync: Now pulls an interactive index from the community repository. You can discover, preview, and install curated vaults via fzf without needing to manually track remote filenames.
• Expanded Vaults: New curated vaults for Docker, Security Auditing, Nix, and Neovim are now available.
• macOS Power Kit: Massive thanks to the r/MacOS community for contributing the "Graybeard" BSD one-liners that make this the most comprehensive macOS vault in the engine.

Core Improvements

• Surgical Logic: Refined string manipulation for faster placeholder swapping.
• Duplicate Guards: Improved logic to prevent identical commands from cluttering your vaults.

---

Community Sync

Stop searching the web for the same syntax. XC now includes a built-in sync engine to pull curated, Arch Wiki-verified "Problem-Solution" vaults directly from this repository.

Vault	Command	Description
Arch Linux	xc sync arch	Fixes for PGP keyrings, .pacnew merges, and kernel maintenance.
Debian	xc sync debian	Apt repository tracking, kernel upgrades, and package maintenance.
Docker Dev	xc sync docker-dev	Container lifecycle management and aggressive resource cleanup.
Fedora	xc sync fedora	DNF transaction history, security updates, and repository management.
General Nix	xc sync general-nix	Essential POSIX utilities for permissions, disk usage, and IO.
Git Pro	xc sync git-pro	Advanced recovery, reflog navigation, and surgical commit tools.
Hyprland	xc sync hyprland	Wayland specific fixes for NVIDIA, portals, and window rules.
MacOS	xc sync macos	High-utility BSD maintenance, Gatekeeper fixes, and hidden system tweaks
Networking	xc sync networking	Connectivity diagnostics, DNS lookups, and interface auditing.
OpenSUSE	xc sync opensuse	Zypper distribution upgrades, process tracking, and system repair.
Security Audit	xc sync security-audit	Local hardening, SUID discovery, and system integrity logs.
Templates	xc sync templates	Interactive snippets using placeholders for Git, SSH, and more.
Vim/Neovim	xc sync vim-neovim	High-speed motions, global search/replace, and health checks.

---

Features

• Interactive Template Engine: Support for {{placeholders}} that prompt for user input during execution. [v0.7.0]
• Global Variable Mapping: Identical placeholder names trigger a single prompt to save keystrokes. [v0.7.0]
• Vault Package Manager: Interactive sync interface to browse and download community-curated vaults. [v0.7.0]
• Proactive Saving: Run a command and save it immediately.
• Retroactive Saving: Save the last command you ran without retyping it.
• FZF Integration: Search your vault with fuzzy finding and live previews.
• Alias Export Engine: Convert any saved command into a permanent Zsh alias instantly with Alt-E.
• Collision Detection: Built-in safety checks prevent you from accidentally overwriting system commands or existing aliases.
• Modular Configuration: Choose your "Source of Truth" save to ~/.zshrc or keep it clean with a dedicated ~/.zsh_aliases file.
• Instant Activation: Exported aliases are injected into your current session immediately, no shell restart required.
• Ligature Friendly: Uses standard ASCII -> that renders as a sleek arrow in Nerd Fonts.
• Zero-Lag: Uses Zsh autoload for near-instant shell startup.
• Smart History: Save the last command or select from your recent history.
• Safe Maintenance: Built-in transparent cleanup for duplicates.
• Distro Agnostic: Works on Arch, Fedora, Debian, and macOS.
• Toggable Search: Seamlessly switch between local vault and global search using Ctrl-A and Ctrl-R without exiting the TUI.

Requirements

• zsh
• fzf
• sed (The line-editor for deletions)
• grep (The standard search tool)

Installation

Arch Linux (AUR)

The package is available in the AUR as xc-manager-git.

yay -S xc-manager-git

All other linux distros and MacOS

Clone the repository:

git clone https://github.com/Rakosn1cek/xc-manager.git ~/.zsh-plugins/xc-manager

Add to your ~/.zshrc:

# Add to function path and autoload
# For AUR users: 
source /usr/share/zsh/plugins/xc-manager/xc.plugin.zsh

# For Manual users: 
source ~/.zsh-plugins/xc-manager/xc.plugin.zsh

[[ -f ~/.zsh_aliases ]] && source ~/.zsh_aliases

# All distros including MacOS
HISTFILE=~/.zsh_history
HISTSIZE=10000
SAVEHIST=10000
setopt appendhistory

Optional UI Customisation

zstyle ':xc:*' separator "->" 
zstyle ':xc:*' fzf_colors "fg:7,hl:4,fg+:15,hl+:12,info:2,prompt:5,pointer:12"

Reload your shell:

source ~/.zshrc

Initialise the vault (First time only):

xc init

Usage

Community Sync (v0.7.0)

• Interactive Sync: Run xc sync without arguments to browse and select from the community index via fzf.
• Templates: Run xc sync templates to download pre-configured interactive snippets for Git, SSH, and Docker.

Interactive Templating (New in v0.7.0)

• Dynamic Prompts: Save commands with {{var}} syntax. Selecting these will trigger interactive prompts for each unique variable.
• Global Mapping: Identical placeholder names (e.g., cp {{file}} {{file}}.bak) will only prompt you once and swap all instances globally.
• Integration: Placeholder logic is fully supported in both the standard TUI (Ctrl-G) and Global Search.
• Safety Guard: Hitting Enter on an empty prompt will cancel the execution, keeping your command line clean and preventing syntax errors.

Community Sync (v0.6.0) XC-Manager now features a built-in sync engine to pull curated "Problem-Solution" vaults directly from the community repository.

• Sync a Vault: Run xc sync (e.g., xc sync arch or xc sync hyprland).
• Available Categories: arch, hyprland, general-nix, git-pro, docker-dev, networking, vim-neovim, security-audit, templates.
• Update: Re-running sync will pull the latest verified fixes from the upstream repo.

Managing Contexts (Multi-Vault) XC allows you to isolate commands into different vaults.

• Switch or Create: Use xc use <name> to toggle your active context.
• Example: xc use work (If it doesn't exist, a new work.txt is created automatically).
• Automatic Selection: Once a vault is active, any command saved via xc or xc select is instantly routed to that specific file.
• Visual Confirmation: Running xc use without arguments highlights the active vault.

Saving Commands

• Capture last command: Run xc to save the command you just executed.
• Select from history: Run xc select to browse your last 100 commands for saving.
• Cleanup: Run xc clean to scrub duplicates and empty entries from the active vault.

Retrieving Commands

• Launch TUI: Press Ctrl + G anywhere in your terminal.
• Filter: Type to fuzzy search. The description appears in the preview box.
• Execute: Press Enter to load the command into your prompt.
• Delete: Press Alt + D inside the TUI to delete the selected entry.

Search across all vaults

• Global Search: Pressing Ctrl-A while in the TUI (Ctrl-G) will expand your search to every vault in your collection. This mode is for searching and selecting commands only for safety. Delete (Alt-D) is disabled by default.
• Deduplication: As of v0.6.1, redundant commands across multiple vaults are filtered out to reduce visual noise.
• Safety First: Global Search remains Read-Only. Because this search can pull from high-risk maintenance vaults (like arch or security), it serves as a reference to prevent accidental execution of sensitive commands.

Exporting Aliases (v0.5.0+)

• Open the vault: Ctrl-G(or your custom binding).
• Highlight a command: and press Alt-E.
• Type a name for your alias and hit Enter.
• The alias is now saved and active! Remember, as of v0.5.0-beta Aliases are saved by default to ~/.zsh_aliases. If you prefer to save them directly into your main config file, add this to your .zshrc:

export XC_ALIAS_TARGET="$HOME/.zshrc"

Utilities

• Check version: xc -v

Configuration (Optional)

Customise the look of your vault using Zsh's zstyle system:

zstyle ':xc:*' fzf_colors "gutter:-1,border:8,header:4,info:2,pointer:5,marker:13,fg+:7,prompt:5,hl:12"

Recommended Integrations

Alias Browser (als) If you want an easy way to browse and run your newly created aliases using fzf, I highly recommend checking out my show-aliases.sh script. It searches both your .zshrc and .zsh_aliases to give you a unified, interactive menu.

• View Script: on GitHub Show-Aliases Script
• Key Feature: Seamlessly displays XC exports alongside your manual system aliases.

Roadmap

[x] Modular Architecture: Refactored to Zsh autoload for instant startup.

[x] Native Delete Feature: Alt+D keybinding to remove entries directly from the TUI.

[x] Vault Cleanup: Automatic removal of duplicates or empty descriptions.

[x] Multi-Vault Support: Ability to switch between different context files.

[x] Export to Alias: Export vault commands directly to .zshrc as permanent aliases.

[x] Global Search: Search across all vaults simultaneously.

[x] Community Sync Engine (v0.6.0): Built-in distribution system to pull curated, Wiki-verified vaults (Arch, Hyprland, Git, etc.) directly from GitHub.

[x] Dynamic Placeholders: Support for {{variable}} prompting within vaulted commands.

[ ] Encrypted Vaults: Support for gpg or age encrypted .txt files for sensitive commands.

[ ] Cross-Shell Research: Investigating a POSIX-compliant core for Bash and Fish support.

Maintenance & Stability

This project follows the KISS (Keep It Simple, Stupid) principle. Because it relies on standard Unix tools and native Zsh functions, it is designed to be "set and forget".

• Feature Complete: v0.5.0-beta contains the core intended workflow. I don't plan on adding heavy dependencies or feature bloat.
• Long-term Support: As an Arch user, I use this tool daily. I will provide active maintenance for bug fixes and Zsh compatibility updates.
• Plain Text Forever: Your vaults are stored in simple .txt files. Your data remains portable and human readable regardless of the tool.

Support & Feedback

• Bug Reports: If something isn't working, especially with the Alias Export engine, please open an Issue.
• Feature Ideas: To discuss the roadmap or suggest a polish, head over to theDiscussions tab.
• Community Snippets: Have a complex one-liner you've vaulted? Share it in the "Show and Tell" discussion.

License

Distributed under the MIT License. See LICENSE for more information.

Changelog

For a detailed history of changes and version milestones, please see CHANGELOG.md.

Support the Project

If XC makes your workflow faster or your .zshrc cleaner, please consider giving it a Star on GitHub! It helps other Arch users find the project and keeps the development of features like v0.5.0-beta going.

Project Note: This documentation and parts of the shell optimisation were proofread and refined with the help of LLMs to ensure clarity and performance.

⭐ Star XC-Manager on GitHub