config-central/docs/advanced_commands.md

20 KiB

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. 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:

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:

$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:

& ([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.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:

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:

& ([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:

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:

& ([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 web updater leaves the installed cc checkout unchanged. Run cc update-software to refresh the CLI and installed software, or rerun setup with -SkipApply when you only want to repair the checkout and launcher.

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.

{
  "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%:

{
  "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.

MPC-HC, Ontime, XnView MP, Nextcloud, and Windows hosts configuration have application-specific safety rules. See the desktop application configuration guide before populating those declarations.

Daily commands

cc plan                         # show intended work; change nothing
cc apply                        # apply the current checkout
cc sync                         # fetch and apply an immutable remote snapshot
cc update-software              # refresh cc, then update declared software
cc software-update              # alias for update-software
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. 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:

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:

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. Runtime failures in setup, bootstrap, updates, capture, and SSH helpers use the same concise error presentation. Native installer diagnostics remain visible; PowerShell parameter-binding or syntax errors can still use PowerShell formatting.

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:

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

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:

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.
  • Deletion of formerly managed configs remains manual. Removing a package entry only stops management; an explicit WinGet state: "absent" policy uninstalls that exact package.

Item results color status labels; script summaries use the same palette: red errors, yellow warnings, green completion, gray unchanged items, and cyan planned actions. Redirected output and JSON remain plain. Set $env:NO_COLOR = "1" to disable colors in a terminal. Errors go to stderr; JSON errors stay structured. Runtime failures preserve nonzero status codes, and web commands leave the terminal open with the outcome in $LASTEXITCODE.

Portable package updates

The desktop profile includes Deckstride 0.1.96 and PPTX Reporter 0.2.0 for Windows x64 from their published portable releases. Their exact ZIP hashes and executable paths were checked against each release's SHA256SUMS and artifact manifest. The Windows binaries are unsigned; native Windows acceptance remains pending here too.

Portable packages use provider: "portable", user scope and a version pinned in Git. source is a namespace (here idle-org), not a WinGet source. They appear alongside WinGet packages in cc plan, cc status, cc apply and full cc sync. Config-only commands and the scheduled config sync leave software alone.

To update installed software, close Deckstride and PPTX Reporter and run:

cc update-software

cc software-update runs the same command. In an interactive terminal the outer command shows an elapsed spinner while the refreshed snapshot works. Redirected output gets one plain start line; -Json suppresses progress output.

The command fetches the configured repository branch and continues from an immutable snapshot of that commit, so the current run uses the latest Config Central code and policy. It then checks the Gitea releases API for opted-in portable packages and asks WinGet to apply each declared package's policy by exact ID. Deckstride follows the newest eligible stable release. Unmanaged WinGet applications are left alone. Configs are not planned or changed. The profile declares Pympress absent, so each software run silently leaves it alone when missing and uninstalls it by exact WinGet ID when found. Each release lookup resolves one exact ZIP, reads its exact entry from SHA256SUMS, and verifies the downloaded archive before activation. Both tools follow stable releases. A lookup or checksum failure is reported for that package while independent packages continue. As with sync, local checkout changes must be committed or removed before the fetch; Config Central never discards them automatically. After the software run, the installed checkout is advanced to the resolved commit with a fast-forward-only merge so subsequent cc commands use the refreshed version.

To review and advance the deterministic repository pin:

  1. Select and review an upstream release, download its Windows portable ZIP, and compare Get-FileHash -Algorithm SHA256 with its published SHA256SUMS.
  2. Update version, url, sha256 and executable together in profiles/desktop-apps.json. Use the version-specific download URL. These fields remain the reviewed fallback used by apply and sync; only the explicit update-software command follows the configured release channel.
  3. Commit and push the change. cc sync applies that pin on each desktop. Use cc apply for an updated local checkout; cc plan previews the pin without contacting the release API or downloading it.

Default files live under %LOCALAPPDATA%\ConfigCentral\apps\idle-org\deckstride. launch.ps1 is the stable terminal launcher; the Start menu shortcut under Config Central\idle-org targets deckstride.exe directly and uses its embedded icon. current.json records the active version and hashes. A successful update removes older managed version directories. The working version remains active when download, verification, or setup fails. Removing the profile entry does not uninstall anything.

The package also declares displayName, fileAssociations, and a dedicated fileAssociationIcon, which register Deckstride per user as a .pdf handler with Windows Default Apps. Config Central copies the icon into the stable package root so Explorer does not depend on a versioned executable. The open command passes the selected PDF directly to the active executable. Windows requires the user to confirm the protected default-app choice. After applying the package, open its settings page and select Deckstride for .pdf:

Start-Process 'ms-settings:defaultapps?registeredAppUser=ConfigCentral.idle-org.deckstride'

Updates repair the registration to point at the new verified executable without rewriting the user's default-app preference.

Deckstride's declaration includes a replaces entry for idle-org/pdf-presenter. On the first successful update, Config Central activates Deckstride before removing PDF Presenter's managed files, shortcut and old .pdf registration, including PDF Presenter's own obsolete Default Apps and Open With ProgID entries. If the old installation was locally modified or cannot be removed, Deckstride stays installed and cleanup is retried later. Select Deckstride once in Windows Default Apps because Windows does not allow software to transfer the protected .pdf default choice to a renamed handler.

On a failed download, checksum check or setup step, fix the reported cause and retry. Missing managed files are repaired. Locally changed binaries or launchers are conflicts: inspect and save those changes elsewhere, then remove the affected file to let the next apply repair it. -ForceConfigs does not override portable package conflicts. Never change the hash of an existing release to bypass a checksum mismatch. Cleanup failures are warnings and are retried on the next run without another download. Persistent application settings must live outside the managed version directory because older versions are deleted after activation.

Linux Pester tests cover archive validation, hash verification, partial failure, retry, version policies, conflict handling, launcher errors and elevation rejection. Disposable Windows x64 acceptance still needs to verify first install, Start menu launch, a no-change rerun, running-app refusal, and an upgrade with settings preserved. Run the controller as the desktop user, not as a separate administrator account.