Add headless automation daemon and CLI

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mamoreau-devolutions

.github/workflows/cli-headless-e2e.yml

@@ -0,0 +1,68 @@
+name: CLI Headless E2E
+
+on:
+  push:
+    paths:
+      - 'src/**/*.cs'
+      - 'src/**/*.csproj'
+      - 'src/**/*.props'
+      - 'src/**/*.targets'
+      - 'src/**/*.sln'
+      - 'src/**/*.slnx'
+      - 'testing/automation/**'
+      - '.github/workflows/cli-headless-e2e.yml'
+      - 'global.json'
+  pull_request:
+    branches: [ "main" ]
+    paths:
+      - 'src/**/*.cs'
+      - 'src/**/*.csproj'
+      - 'src/**/*.props'
+      - 'src/**/*.targets'
+      - 'src/**/*.sln'
+      - 'src/**/*.slnx'
+      - 'testing/automation/**'
+      - '.github/workflows/cli-headless-e2e.yml'
+      - 'global.json'
+  workflow_dispatch:
+
+jobs:
+  cli-headless-e2e:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, macos-latest, ubuntu-latest]
+
+    runs-on: ${{ matrix.os }}
+    env:
+      CONFIGURATION: Release
+      NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@v5
+        with:
+          global-json-file: global.json
+
+      - name: Cache NuGet packages
+        uses: actions/cache@v5
+        with:
+          path: ${{ env.NUGET_PACKAGES }}
+          key: ${{ runner.os }}-nuget-e2e-${{ hashFiles('global.json', 'src/**/*.csproj', 'src/**/*.props', 'src/**/*.targets', 'src/**/*.sln', 'src/**/*.slnx') }}
+          restore-keys: |
+            ${{ runner.os }}-nuget-e2e-
+
+      - name: Restore Avalonia solution
+        working-directory: src
+        run: dotnet restore UniGetUI.Avalonia.slnx
+
+      - name: Build Avalonia solution
+        working-directory: src
+        run: dotnet build UniGetUI.Avalonia.slnx --no-restore --configuration ${{ env.CONFIGURATION }} --verbosity minimal
+
+      - name: Run headless CLI E2E
+        shell: pwsh
+        run: ./testing/automation/run-cli-e2e.ps1

cli-arguments.md

@@ -17,13 +17,38 @@
 | `--no-corrupt-dialog` | Will show a verbose error message (the error report) instead of a simplified message dialog | 3.2.1+ |
 | `--[enable\|disable]-secure-setting-for-user username key` | Enables/disables the given secure setting for the given key<sup>2</sup> and username. Requires administrator rights.  | 3.2.1+ | 
 | `--[enable\|disable]-secure-setting key` | Enables/disables the given secure setting<sup>2</sup> for current user. This will generate a UAC prompt  | 3.2.1+ | 
+| `--headless` | Starts the Avalonia host as a pure automation daemon with **no UI** and no requirement for a working graphical environment. Compatible with `--background-api-*` transport arguments. | 2026.1+ |
+| `--automation status` | Queries the local automation service and returns machine-readable status, including the configured background API transport | 2026.1+ |
+| `--automation get-version` | Reads the local automation service build number through the background API | 2026.1+ |
+| `--automation get-updates` | Reads the currently available updates through the local automation service and returns structured JSON | 2026.1+ |
+| `--automation list-installed --manager name` | Lists installed packages for the selected manager through the automation service and returns structured JSON | 2026.1+ |
+| `--automation search-packages --manager name --query text [--max-results n]` | Searches packages through the automation service and returns structured JSON | 2026.1+ |
+| `--automation install-package --manager name --package-id id [--version v] [--scope scope] [--pre-release]` | Installs a package through the automation service and waits for completion | 2026.1+ |
+| `--automation open-window` | Asks the running UniGetUI instance to show the main window | 2026.1+ |
+| `--automation open-updates` | Asks the running UniGetUI instance to show the Updates page | 2026.1+ |
+| `--automation show-package --package-id id --package-source source` | Opens the package details flow for the specified package | 2026.1+ |
+| `--automation update-all` | Queues updates for all packages currently shown as upgradable | 2026.1+ |
+| `--automation update-manager --manager name` | Queues updates for all packages handled by the specified manager | 2026.1+ |
+| `--automation update-package --manager name --package-id id` | Updates a specific package through the automation service and waits for completion | 2026.1+ |
+| `--automation uninstall-package --manager name --package-id id [--scope scope]` | Uninstalls a package through the automation service and waits for completion | 2026.1+ |
+| `--background-api-transport {tcp\|named-pipe}` | Selects which local HTTP transport UniGetUI uses for the background API when the app starts | 2026.1+ |
+| `--background-api-port port` | Overrides the localhost TCP port used by the background API when `--background-api-transport tcp` is active | 2026.1+ |
+| `--background-api-pipe-name name` | Overrides the Windows named pipe name used by the background API when `--background-api-transport named-pipe` is active | 2026.1+ |
+| `--transport {tcp\|named-pipe}` | Overrides the client-side automation transport used by `--automation ...` commands | 2026.1+ |
+| `--tcp-port port` | Overrides the client-side localhost TCP port used by `--automation ...` commands | 2026.1+ |
+| `--pipe-name name` | Overrides the client-side named pipe used by `--automation ...` commands | 2026.1+ |
 
 1. See the available list of setting keys [here](https://github.com/Devolutions/UniGetUI/blob/fc98f312a72b80e14a8ac10687f4fc506a5c9cc4/src/UniGetUI.Core.Settings/SettingsEngine_Names.cs#L5)
 2. See the available list of secure settings keys [here](https://github.com/Devolutions/UniGetUI/blob/fc98f312a72b80e14a8ac10687f4fc506a5c9cc4/src/UniGetUI.Core.SecureSettings/SecureSettings.cs#L10)
 
 
 \*After modifying the settings, you must ensure that any running instance of UniGetUI is restarted for the changes to take effect
 
+## Headless automation daemon and cross-platform CLI
+
+- `dotnet src\UniGetUI.Avalonia\bin\Release\net10.0\UniGetUI.Avalonia.dll --headless` starts the local automation daemon without opening any window or requiring a graphical desktop session.
+- `dotnet src\UniGetUI.Cli\bin\Release\net10.0\UniGetUI.Cli.dll <command>` is the cross-platform CLI wrapper for the automation service. It automatically prepends `--automation`, so `UniGetUI.Cli status` and `UniGetUI.Cli search-packages --manager ".NET Tool" --query dotnetsay` work directly.
+
 <br><br>
 # `unigetui://` deep link
 On a system where UniGetUI 3.1.2+ is installed, the following deep links can be used to communicate with UniGetUI:

src/UniGetUI.Avalonia.slnx

@@ -213,4 +213,8 @@
       <Platform Solution="*|x64" Project="x64" />
     </Project>
   </Folder>
+  <Project Path="UniGetUI.Cli/UniGetUI.Cli.csproj">
+    <Platform Solution="*|arm64" Project="arm64" />
+    <Platform Solution="*|x64" Project="x64" />
+  </Project>
 </Solution>

src/UniGetUI.Avalonia/App.axaml.cs

@@ -1,4 +1,3 @@
-using System.Diagnostics;
 using Avalonia;
 using Avalonia.Controls.ApplicationLifetimes;
 using Avalonia.Markup.Xaml;
@@ -37,12 +36,16 @@ public override void OnFrameworkInitializationCompleted()
         {
             if (OperatingSystem.IsMacOS())
             {
-                ExpandMacOSPath();
+                ProcessEnvironmentConfigurator.PrepareForCurrentPlatform();
                 using var stream = AssetLoader.Open(new Uri("avares://UniGetUI.Avalonia/Assets/icon.png"));
                 using var ms = new MemoryStream();
                 stream.CopyTo(ms);
                 MacOsNotificationBridge.SetDockIcon(ms.ToArray());
             }
+            else
+            {
+                ProcessEnvironmentConfigurator.ApplyProxySettingsToProcess();
+            }
             PEInterface.LoadLoaders();
             ApplyTheme(CoreSettings.GetValue(CoreSettings.K.PreferredTheme));
             var mainWindow = new MainWindow();
@@ -53,33 +56,6 @@ public override void OnFrameworkInitializationCompleted()
         base.OnFrameworkInitializationCompleted();
     }
 
-    /// <summary>
-    /// macOS GUI apps start with a minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin).
-    /// Ask the user's login shell for its full PATH so package managers (npm, pip,
-    /// cargo, brew-installed tools, …) can be found.
-    /// </summary>
-    private static void ExpandMacOSPath()
-    {
-        try
-        {
-            using var process = new Process
-            {
-                StartInfo = new ProcessStartInfo("zsh", ["-l", "-c", "printenv PATH"])
-                {
-                    UseShellExecute = false,
-                    RedirectStandardOutput = true,
-                    CreateNoWindow = true,
-                },
-            };
-            process.Start();
-            string shellPath = process.StandardOutput.ReadToEnd().Trim();
-            process.WaitForExit(5000);
-            if (!string.IsNullOrEmpty(shellPath))
-                Environment.SetEnvironmentVariable("PATH", shellPath);
-        }
-        catch { /* keep the existing PATH if the shell can't be launched */ }
-    }
-
     public static void ApplyTheme(string value)
     {
         Current!.RequestedThemeVariant = value switch

src/UniGetUI.Avalonia/Infrastructure/AvaloniaBootstrapper.cs

@@ -40,7 +40,7 @@ await Task.WhenAll(
     private static Task InitializeSharedServicesAsync()
     {
         CoreTools.ReloadLanguageEngineInstance();
-        MainWindow.ApplyProxyVariableToProcess();
+        ProcessEnvironmentConfigurator.ApplyProxySettingsToProcess();
         _ = Task.Run(AvaloniaAutoUpdater.UpdateCheckLoopAsync)
             .ContinueWith(
                 t => Logger.Error(t.Exception!),

src/UniGetUI.Avalonia/Infrastructure/HeadlessDaemonHost.cs

@@ -0,0 +1,63 @@
+using UniGetUI.Core.Logging;
+using UniGetUI.Interface;
+using UniGetUI.PackageEngine;
+
+namespace UniGetUI.Avalonia.Infrastructure;
+
+internal static class HeadlessDaemonHost
+{
+    public static async Task<int> RunAsync(string[] args)
+    {
+        BackgroundApiRunner? backgroundApi = null;
+        using var shutdown = new CancellationTokenSource();
+
+        Console.CancelKeyPress += (_, eventArgs) =>
+        {
+            eventArgs.Cancel = true;
+            shutdown.Cancel();
+        };
+
+        AppDomain.CurrentDomain.ProcessExit += (_, _) => shutdown.Cancel();
+
+        try
+        {
+            Logger.Info("Starting UniGetUI headless daemon");
+
+            ProcessEnvironmentConfigurator.PrepareForCurrentPlatform();
+            PEInterface.LoadLoaders();
+            await Task.Run(PEInterface.LoadManagers);
+
+            backgroundApi = new BackgroundApiRunner();
+            await backgroundApi.Start();
+
+            Logger.Info("UniGetUI headless daemon is ready");
+            await WaitForShutdownAsync(shutdown.Token);
+            return 0;
+        }
+        catch (Exception ex)
+        {
+            Logger.Error("UniGetUI headless daemon failed to start");
+            Logger.Error(ex);
+            return ex.HResult != 0 ? ex.HResult : 1;
+        }
+        finally
+        {
+            if (backgroundApi is not null)
+            {
+                await backgroundApi.Stop();
+            }
+        }
+    }
+
+    private static Task WaitForShutdownAsync(CancellationToken cancellationToken)
+    {
+        if (cancellationToken.IsCancellationRequested)
+        {
+            return Task.CompletedTask;
+        }
+
+        var completion = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
+        cancellationToken.Register(() => completion.TrySetResult());
+        return completion.Task;
+    }
+}

src/UniGetUI.Avalonia/Infrastructure/HeadlessModeOptions.cs

@@ -0,0 +1,13 @@
+namespace UniGetUI.Avalonia.Infrastructure;
+
+internal static class HeadlessModeOptions
+{
+    public const string HeadlessArgument = "--headless";
+    public const string DaemonArgument = "--daemon";
+
+    public static bool IsHeadless(IReadOnlyList<string> args)
+    {
+        return args.Contains(HeadlessArgument, StringComparer.OrdinalIgnoreCase)
+            || args.Contains(DaemonArgument, StringComparer.OrdinalIgnoreCase);
+    }
+}

src/UniGetUI.Avalonia/Infrastructure/ProcessEnvironmentConfigurator.cs

@@ -0,0 +1,85 @@
+using System.Diagnostics;
+using UniGetUI.Core.Logging;
+using UniGetUI.Core.SettingsEngine;
+
+namespace UniGetUI.Avalonia.Infrastructure;
+
+internal static class ProcessEnvironmentConfigurator
+{
+    public static void PrepareForCurrentPlatform()
+    {
+        if (OperatingSystem.IsMacOS())
+        {
+            ExpandMacOSPath();
+        }
+
+        ApplyProxySettingsToProcess();
+    }
+
+    public static void ApplyProxySettingsToProcess()
+    {
+        try
+        {
+            var proxyUri = Settings.GetProxyUrl();
+            if (proxyUri is null || !Settings.Get(Settings.K.EnableProxy))
+            {
+                Environment.SetEnvironmentVariable("HTTP_PROXY", "", EnvironmentVariableTarget.Process);
+                return;
+            }
+
+            string content;
+            if (!Settings.Get(Settings.K.EnableProxyAuth))
+            {
+                content = proxyUri.ToString();
+            }
+            else
+            {
+                var creds = Settings.GetProxyCredentials();
+                if (creds is null)
+                {
+                    content = proxyUri.ToString();
+                }
+                else
+                {
+                    content = $"{proxyUri.Scheme}://{Uri.EscapeDataString(creds.UserName)}"
+                            + $":{Uri.EscapeDataString(creds.Password)}"
+                            + $"@{proxyUri.AbsoluteUri.Replace($"{proxyUri.Scheme}://", "")}";
+                }
+            }
+
+            Environment.SetEnvironmentVariable("HTTP_PROXY", content, EnvironmentVariableTarget.Process);
+        }
+        catch (Exception ex)
+        {
+            Logger.Error("Failed to apply proxy settings:");
+            Logger.Error(ex);
+        }
+    }
+
+    private static void ExpandMacOSPath()
+    {
+        try
+        {
+            using var process = new Process
+            {
+                StartInfo = new ProcessStartInfo("zsh", ["-l", "-c", "printenv PATH"])
+                {
+                    UseShellExecute = false,
+                    RedirectStandardOutput = true,
+                    CreateNoWindow = true,
+                },
+            };
+            process.Start();
+            string shellPath = process.StandardOutput.ReadToEnd().Trim();
+            process.WaitForExit(5000);
+            if (!string.IsNullOrEmpty(shellPath))
+            {
+                Environment.SetEnvironmentVariable("PATH", shellPath);
+            }
+        }
+        catch
+        {
+            // Keep the existing PATH if the shell can't be launched.
+        }
+    }
+}

src/UniGetUI.Avalonia/Program.cs

@@ -1,5 +1,6 @@
 using System;
 using Avalonia;
+using UniGetUI.Avalonia.Infrastructure;
 
 namespace UniGetUI.Avalonia;
 
@@ -9,8 +10,16 @@ sealed class Program
     // SynchronizationContext-reliant code before AppMain is called: things aren't initialized
     // yet and stuff might break.
     [STAThread]
-    public static void Main(string[] args) => BuildAvaloniaApp()
-        .StartWithClassicDesktopLifetime(args);
+    public static void Main(string[] args)
+    {
+        if (HeadlessModeOptions.IsHeadless(args))
+        {
+            Environment.ExitCode = HeadlessDaemonHost.RunAsync(args).GetAwaiter().GetResult();
+            return;
+        }
+
+        BuildAvaloniaApp().StartWithClassicDesktopLifetime(args);
+    }
 
     // Avalonia configuration, don't remove; also used by visual designer.
     public static AppBuilder BuildAvaloniaApp()

src/UniGetUI.Avalonia/UniGetUI.Avalonia.csproj

@@ -94,6 +94,9 @@
       <Compile Include="Infrastructure\AvaloniaPackageOperationHelper.cs" />
       <Compile Include="Infrastructure\GitHubAuthService.cs" />
       <Compile Include="Infrastructure\GitHubCloudBackupService.cs" />
+      <Compile Include="Infrastructure\HeadlessDaemonHost.cs" />
+      <Compile Include="Infrastructure\HeadlessModeOptions.cs" />
+      <Compile Include="Infrastructure\ProcessEnvironmentConfigurator.cs" />
       <Compile Include="Infrastructure\RelayCommand.cs" />
       <Compile Include="Infrastructure\SingleInstanceRedirector.cs" />
       <Compile Include="Infrastructure\UninstallConfirmationDialog.cs" />