Add shell-init command emitting a changeset-net shell function

net-changesets and the Node @changesets CLI share the `changeset` command
name, and a .NET tool can expose only one command (the SDK rejects a
multi-command tool package), so there is no packaged way to add a second
name. `changeset shell-init <shell>` prints a shell function (zsh/bash/pwsh)
that points `changeset-net` at the net-changesets binary directly, so it
always runs net-changesets regardless of PATH order.

- New ShellInitCommand + registration; raw stdout so `eval "$(...)"` works.
- E2E tests, changeset, and a README "Using alongside @changesets" section.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: JohnCampionJr

.changeset/shell-init.md

@@ -0,0 +1,5 @@
+---
+"SolarWinds.Changesets": Minor
+---
+
+Add a `shell-init` command that prints a shell snippet defining a `changeset-net` function (for zsh, bash, and pwsh). net-changesets and the Node `@changesets` CLI share the `changeset` command name, and a .NET tool can expose only one command, so there is no packaged way to add a second name. `changeset-net` points at the net-changesets binary directly, so it always runs net-changesets even when `changeset` resolves to the Node tool on your PATH. Enable it with `eval "$(changeset shell-init zsh)"` (or the pwsh equivalent).

README.md

@@ -44,6 +44,23 @@ intentional gaps:
   `changelog-github` (PR links + commit links + author thanks) generators are not implemented. They may be
   added in a future update if needed or requested.
 
+## Using alongside @changesets (Node)
+
+net-changesets installs the `changeset` command — the same name as the Node `@changesets` CLI. When both are
+installed globally, whichever comes first on your `PATH` wins, and a .NET tool can expose only one command, so
+there is no built-in second name. To always reach net-changesets regardless of `PATH`, add its `changeset-net`
+shell function:
+
+```bash
+# zsh (~/.zshrc) — bash and pwsh are also supported
+eval "$(changeset shell-init zsh)"
+```
+
+`changeset shell-init <shell>` prints the snippet; run `changeset shell-init` for setup instructions. In a
+polyglot repo the smoothest setup is to let net-changesets own `changeset` (it leaves Node changesets untouched
+and guides you to the Node tool when there are no .NET projects), using `changeset-net` only when the Node tool
+owns `changeset`.
+
 ## Documentation
 
 - [Implementation Details of net-changesets commands](https://github.com/solarwinds/net-changesets/blob/main/docs/commands-implementation-details.md)

src/SolarWinds.Changesets/Commands/ShellInit/ShellInitCommand.cs

@@ -0,0 +1,89 @@
+using Spectre.Console.Cli;
+
+namespace SolarWinds.Changesets.Commands.ShellInit;
+
+/// <summary>
+/// Prints a shell snippet that defines a <c>changeset-net</c> command pointing at this net-changesets binary.
+/// Because net-changesets and the Node <c>@changesets</c> CLI share the command name <c>changeset</c> (and a
+/// .NET tool may expose only one command), there is no packaged way to add a second name. A shell function is
+/// the workaround: <c>changeset-net</c> always runs net-changesets, even when <c>changeset</c> resolves to the
+/// Node tool on the user's PATH. Use it via <c>eval "$(changeset shell-init zsh)"</c> (or the pwsh form).
+/// </summary>
+internal sealed class ShellInitCommand : Command<ShellInitCommandSettings>
+{
+    private static readonly string[] s_shells = ["zsh", "bash", "pwsh"];
+
+    public static string Name { get; } = "shell-init";
+
+    public static string Description { get; } =
+        "Print a shell snippet that defines a 'changeset-net' command for invoking net-changesets directly.";
+
+    protected override int Execute(CommandContext context, ShellInitCommandSettings settings, CancellationToken cancellationToken)
+    {
+        // The path to this binary, so the emitted command always reaches net-changesets regardless of PATH
+        // order. For an installed global tool this is the tool shim (for example ~/.dotnet/tools/changeset).
+        string net = Environment.ProcessPath ?? "changeset";
+
+        // Raw stdout throughout (Spectre1000 suppressed deliberately): the snippet is meant to be captured by
+        // `eval "$(...)"`, so it must not be wrapped to terminal width or marked up, which AnsiConsole would do.
+#pragma warning disable Spectre1000 // Use AnsiConsole instead of System.Console
+        // No shell → show how to enable it (this is what users run first).
+        if (string.IsNullOrWhiteSpace(settings.Shell))
+        {
+            Console.WriteLine(Instructions(net));
+            return 0;
+        }
+
+        if (!s_shells.Contains(settings.Shell, StringComparer.OrdinalIgnoreCase))
+        {
+            Console.Error.WriteLine($"Unknown shell '{settings.Shell}'. Supported: {string.Join(", ", s_shells)}.");
+            return 1;
+        }
+
+        string snippet = string.Equals(settings.Shell, "pwsh", StringComparison.OrdinalIgnoreCase)
+            ? PwshSnippet(net)
+            : string.Equals(settings.Shell, "bash", StringComparison.OrdinalIgnoreCase)
+                ? PosixSnippet(net, "~/.bashrc", "bash")
+                : PosixSnippet(net, "~/.zshrc", "zsh");
+
+        Console.WriteLine(snippet);
+#pragma warning restore Spectre1000
+        return 0;
+    }
+
+    private static string Instructions(string net) =>
+        $"""
+        Define a `changeset-net` command that always runs net-changesets, even when the shared `changeset`
+        command resolves to the Node @changesets CLI on your PATH.
+
+        Add the line for your shell to its startup file, then restart the shell:
+
+          zsh    ~/.zshrc     eval "$("{net}" shell-init zsh)"
+          bash   ~/.bashrc    eval "$("{net}" shell-init bash)"
+          pwsh   $PROFILE     Invoke-Expression (& "{net}" shell-init pwsh | Out-String)
+
+        Run `changeset shell-init <shell>` to print the snippet itself.
+        """;
+
+    private static string PosixSnippet(string net, string rcFile, string shell) =>
+        $$"""
+        # net-changesets shell integration. Add this ONE line to {{rcFile}} (don't paste this script):
+        #     eval "$("{{net}}" shell-init {{shell}})"
+        # It defines `changeset-net`, which always runs net-changesets even when the shared `changeset`
+        # command resolves to the Node @changesets CLI on your PATH.
+        changeset-net() {
+          command "{{net}}" "$@"
+        }
+        """;
+
+    private static string PwshSnippet(string net) =>
+        $$"""
+        # net-changesets shell integration. Add this line to $PROFILE (don't paste this script):
+        #     Invoke-Expression (& "{{net}}" shell-init pwsh | Out-String)
+        # It defines `changeset-net`, which always runs net-changesets even when the shared `changeset`
+        # command resolves to the Node @changesets CLI on your PATH.
+        function changeset-net {
+          & "{{net}}" @args
+        }
+        """;
+}

src/SolarWinds.Changesets/Commands/ShellInit/ShellInitCommandSettings.cs

@@ -0,0 +1,11 @@
+using System.ComponentModel;
+using Spectre.Console.Cli;
+
+namespace SolarWinds.Changesets.Commands.ShellInit;
+
+internal sealed class ShellInitCommandSettings : CommandSettings
+{
+    [CommandArgument(0, "[shell]")]
+    [Description("The shell to emit the snippet for: 'zsh', 'bash', or 'pwsh'. Omit to print setup instructions.")]
+    public string? Shell { get; init; }
+}

src/SolarWinds.Changesets/Program.cs

@@ -5,6 +5,7 @@
 using SolarWinds.Changesets.Commands.Pre;
 using SolarWinds.Changesets.Commands.Publish;
 using SolarWinds.Changesets.Commands.Publish.Services;
+using SolarWinds.Changesets.Commands.ShellInit;
 using SolarWinds.Changesets.Commands.Status;
 using SolarWinds.Changesets.Commands.Tag;
 using SolarWinds.Changesets.Commands.Ui;
@@ -113,6 +114,12 @@
         .WithDescription(InfoChangesetCommand.Description)
         .WithExample("info")
         ;
+
+    config
+        .AddCommand<ShellInitCommand>(ShellInitCommand.Name)
+        .WithDescription(ShellInitCommand.Description)
+        .WithExample("shell-init", "zsh")
+        ;
 });
 
 return app.Run(args);

tests/SolarWinds.Changesets.Tests/E2E/ShellInitTests.cs

@@ -0,0 +1,48 @@
+using AwesomeAssertions;
+
+namespace SolarWinds.Changesets.Tests.E2E;
+
+/// <summary>
+/// Covers the <c>shell-init</c> command, which emits the <c>changeset-net</c> shell function used to invoke
+/// net-changesets directly when the shared <c>changeset</c> command resolves to the Node tool on PATH.
+/// </summary>
+[TestFixture]
+[Category("E2E")]
+internal sealed class ShellInitTests
+{
+    [Test]
+    public void ShellInit_Zsh_EmitsTheChangesetNetFunction()
+    {
+        CliResult result = ChangesetCli.Run(Environment.CurrentDirectory, "shell-init", "zsh");
+
+        result.ExitCode.Should().Be(0, result.Output);
+        result.Output.Should().Contain("changeset-net()").And.Contain("command ").And.Contain("\"$@\"");
+    }
+
+    [Test]
+    public void ShellInit_Pwsh_EmitsAFunction()
+    {
+        CliResult result = ChangesetCli.Run(Environment.CurrentDirectory, "shell-init", "pwsh");
+
+        result.ExitCode.Should().Be(0, result.Output);
+        result.Output.Should().Contain("function changeset-net").And.Contain("@args");
+    }
+
+    [Test]
+    public void ShellInit_NoShell_PrintsInstructions()
+    {
+        CliResult result = ChangesetCli.Run(Environment.CurrentDirectory, "shell-init");
+
+        result.ExitCode.Should().Be(0, result.Output);
+        result.Output.Should().Contain("changeset-net").And.Contain("startup file");
+    }
+
+    [Test]
+    public void ShellInit_UnknownShell_Fails()
+    {
+        CliResult result = ChangesetCli.Run(Environment.CurrentDirectory, "shell-init", "fish");
+
+        result.ExitCode.Should().NotBe(0);
+        result.Output.Should().Contain("Unknown shell");
+    }
+}