# Advanced commands and maintenance Config Central is a small PowerShell CLI for keeping several Windows desktops on the same declared software and configuration baseline. Each machine pulls this Git repository, resolves its profiles, installs or updates declared packages with WinGet, and copies managed config files with drift detection and backups. For the everyday setup and config-update commands, see the [README](../README.md). This guide covers the installed CLI, customization, and recovery. ## Requirements - Windows 10 version 1809 or newer, Windows 11, or Windows Server 2025 - Windows PowerShell 5.1 for initial bootstrap - PowerShell 7, Git, and WinGet after bootstrap - An interactive desktop account; administrator credentials when a machine-scope installer needs them The bootstrap checks and installs its prerequisites. WinGet must be supported by the Windows edition and able to reach its configured sources. ## Onboard a machine Run the one-stop installer in Windows PowerShell: ```powershell irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/install.ps1' | iex ``` On a new computer, the installer retrieves the machine manifests and selects the only one, matches the Windows computer name, or displays a numbered prompt. On a configured computer it reuses the saved machine automatically. It then stages `bootstrap.ps1` as a temporary file, establishes every prerequisite, clones or updates the repository, and applies the machine manifest. The temporary file is removed afterward. For unattended installation, select the machine in the same command: ```powershell $env:CONFIG_CENTRAL_MACHINE = 'beffroi-laptop'; irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/install.ps1' | iex ``` Setup backs up and replaces existing managed settings by default, just like the web config updater. To preserve local settings and report conflicts during setup: ```powershell & ([scriptblock]::Create((irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/install.ps1'))) -PreserveLocalConfigs ``` The same `-PreserveLocalConfigs` switch is available on `bootstrap.ps1`. `-SkipApply` continues to skip deployment entirely. The installer is safe to rerun for repair or setup updates. Use the web updater for routine config updates. Use `cc sync` when you also want package updates. Download `bootstrap.ps1` from a trusted revision of this repository, inspect it, then run it from Windows PowerShell: ```powershell powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\bootstrap.ps1 ` -Repository 'https://your-server/you/config-central.git' ` -Branch main ` -Machine beffroi-laptop ``` The underlying bootstrap repairs WinGet if necessary, installs Git and PowerShell 7, clones the configured branch under `%LOCALAPPDATA%\ConfigCentral\repository`, saves the machine selection, adds `cc` to the user PATH, and performs the first apply. It is safe to rerun after a failed prerequisite installation. Use `-SkipApply` when you only want to establish the checkout and launcher. A UAC prompt appears only when administrator work is pending and the current terminal is not already elevated. The prompt covers WinGet repair or the batch of machine-scope packages and machine configuration changes. Open a new terminal after bootstrap so the updated user PATH is visible, then check the installation: ```powershell cc doctor cc plan cc apply ``` ### Switching an existing example-desktop setup After pulling this change, rerun the web installer once to replace the saved `example-desktop` selection with `beffroi-laptop`. To refresh setup without deploying configs or packages: ```powershell & ([scriptblock]::Create((irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/install.ps1'))) -Machine beffroi-laptop -SkipApply ``` ## Web config updater After setup, run this in Windows PowerShell or PowerShell 7: ```powershell irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/update-configs.ps1' | iex ``` The script reads the machine, HTTPS repository URL, and branch saved in `%LOCALAPPDATA%\ConfigCentral\settings.json`. It shallow-clones that branch into a temporary directory, checks out the resolved commit, and runs that revision's CLI with `apply -ConfigsOnly`. It removes the temporary checkout afterward. Git and PowerShell 7 must already be installed by setup. There is no machine-selection menu, package installation, or persistent checkout update. Each invocation downloads the current deployment code as well as configs. Existing state, locks, backups, and logs are reused. An administrator prompt may still be required for machine settings such as hosts. Close managed applications first so they do not overwrite deployed settings on exit. The web updater defaults to `-ForceConfigs`: local settings are backed up and replaced with the online versions. To preserve local edits and report conflicts instead, explicitly disable force: ```powershell & ([scriptblock]::Create((irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/update-configs.ps1'))) -ForceConfigs:$false ``` A failed download makes no deployment changes. Partial deployment failures are reported; rerun after correcting the reported problem. The downloaded code runs with your account's permissions, so use a repository you trust. The installed `cc` continues to use its existing local checkout. To refresh that checkout and its CLI for advanced work, rerun setup (use `-SkipApply` if you only want to refresh tooling). The web updater itself needs no such refresh. ## Define profiles and machines Profiles live in `profiles/`. Machines live in `machines/` and list profiles in precedence order. Later profiles replace earlier entries; machine entries replace all profile entries. A package is identified by `source/id`, and a config by `name`. Set `enabled` to `false` in a later layer to remove an inherited item. ```json { "schemaVersion": 1, "name": "workstation", "profiles": ["base", "development"], "packages": [ { "id": "Microsoft.VisualStudioCode", "source": "winget", "scope": "machine", "update": "latest" } ], "configs": [] } ``` Put source files below `configs/`. Config targets accept `%APPDATA%`, `%LOCALAPPDATA%`, `%USERPROFILE%`, and `%PROGRAMDATA%`: ```json { "name": "helix-config", "source": "configs/helix/config.toml", "target": "%APPDATA%/helix/config.toml", "mode": "copy", "requiresPackage": "Helix.Helix" } ``` The complete schema, precedence rules, package policies, and exit codes are in [the manifest contract](manifest-contract.md). MPC-HC, Ontime, XnView MP, Nextcloud, and Windows hosts configuration have application-specific safety rules. See the [desktop application configuration guide](desktop-app-configs.md) before populating those declarations. ## Daily commands ```powershell cc plan # show intended work; change nothing cc apply # apply the current checkout cc sync # fetch and apply an immutable remote snapshot cc status # show drift and the last run cc sync -ConfigsOnly # fetch and deploy configs; do not call WinGet cc apply -ForceConfigs # back up local edits, then replace them cc configs # show repository and live computer config paths cc configs -Config helix-config # show paths for one managed config cc capture # collect live configs under Documents for upload cc capture -Config ontime-style # capture one config cc restore -Config helix-config # restore the newest backup cc doctor # inspect prerequisites and sources cc menu # optional numbered menu ``` For a two-command temporary debugging shell, or for permanent key-based access from CachyOS, follow the [advanced remote access guide](advanced-remote-access.md#quick-temporary-access). The temporary helper prints an SSH command that opens PowerShell directly; ordinary Windows SSH sessions open `cmd.exe`, which does not recognize `irm`. `sync` refuses to run while the checkout has uncommitted or untracked files. It does not reset the checkout. Commit your edits first, or remove files you did not intend to keep. Package installs run sequentially. Machine-scope packages are sent together to a constrained elevated worker, so one UAC approval covers the batch. User config paths come from the original desktop session even when different administrator credentials approve the package work. A required reboot is reported with exit code `6`; Config Central never reboots the machine itself. ## Find and update configuration sources Run `cc configs` on a managed computer to see the repository source and resolved live destination for every config. `Present` means the computer destination exists; `Missing` means the application has not created it yet. Use `-Config NAME` to select one entry, or `-Json` for structured output: ```powershell cc configs cc configs -Config ontime-style cc configs -Config xnviewmp-settings -Json ``` For a `copy` config, close the application, copy the live computer file to the reported repository path, and review `git diff` before committing it. For an `ini-overlay`, copy only the portable keys you intend to manage; do not replace the overlay with the entire application file. Use `tools\Export-MpcHcSettings.ps1` for the MPC-HC registry declaration. Never copy the complete Nextcloud config because it can contain account and authentication data. `cc capture` automates the collection side without changing live files. By default it creates `Documents\ConfigCentral\captures\MACHINE-yyyyMMdd-HHmmss`. Whole-file configs retain their `configs/` repository paths. Raw XnView, hosts, and filtered MPC-HC exports are placed under `review/` for curation. Nextcloud capture reads only keys already allowlisted in `managed.ini`; its account sections and complete config are always excluded. Use `-OutputPath PATH` to select an exact empty destination. From CachyOS, retrieve a completed capture for review with: ```bash scp -r USER@WINDOWS-PC:'Documents/ConfigCentral/captures/MACHINE-yyyyMMdd-HHmmss' ./ ``` ## Setup outcomes When deployment is incomplete, the web installer shows a short summary after the per-item results. Successful changes remain applied. Correct the listed issue and rerun setup. Reboot requests and an already-running update have separate messages. Deployment logs are under `%LOCALAPPDATA%\ConfigCentral\logs`. Running `install.ps1` as a file preserves the bootstrap process exit code. With `irm | iex`, the terminal stays open and `$LASTEXITCODE` contains that code. Errors raised before deployment may still include PowerShell diagnostics. ## Config conflicts and recovery Config Central stores the hash it last deployed. A different destination hash, an existing file it has never managed, or a locally deleted managed file is a conflict. Normal apply leaves the destination alone. `-ForceConfigs` makes a timestamped backup and then deploys the repository version. `cc restore -Config NAME` restores the newest whole-file or INI backup and first backs up the file being replaced. Registry and hosts backups require deliberate manual restoration from an administrator shell. Removing a config from a manifest stops managing it; it does not delete the destination. Removing a package stops managing it; it does not uninstall software. User state is stored under `%LOCALAPPDATA%\ConfigCentral`: ```text settings.json repository, branch, machine, and original user paths state.json deployed hashes, last run, and applied revision logs/ per-run package and config results backups/ timestamped config backups grouped by config name snapshots/ immutable Git commit snapshots used by sync ``` ## Optional logon sync ```powershell cc schedule cc unschedule ``` The scheduled task runs in the interactive user's limited context and always uses `sync -ConfigsOnly`. Package installation remains manual because a logon task must not stall on UAC or an installer prompt. ## Validation On a Windows development machine with Pester 5: ```powershell Invoke-Pester -Path .\tests ``` Real bootstrap, WinGet, UAC, and separate-admin-account tests require a disposable Windows machine. Opt in to the integration suite there with `CONFIG_CENTRAL_INTEGRATION=1`. The Jenkins pipeline follows the project's FreeBSD worker style and runs dependency-free PowerShell structure, JSON contract, and repository hygiene checks; it does not pretend to execute Windows behavior. ## Current limitations - Config deployment supports whole-file copies and the declared application adapters. It does not merge arbitrary application formats. - `latest` packages are offered to WinGet during apply. WinGet decides whether an upgrade exists, so a plan may say `Upgrade` when the installed version is already current. - WinGet inventory contains only packages WinGet recognizes. Unknown versions and installer-specific scope failures are reported with WinGet diagnostics. - Package operations are not transactional and are not rolled back after a later failure. Successful independent work is recorded so the next run can resume. - Config Central does not disable Defender, UAC, malware scanning, or installer integrity checks. - Package removal and deletion of formerly managed configs are deliberately manual operations.