Improve command line options

New --url option instead of --no-browser and overall better documentation of options

Author: 0xced

CHANGELOG.md

@@ -7,6 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ## [Unreleased][Unreleased]
 
 * Fixed an issue where a project reference (blue) could be wrongly identified as package reference (green)
+* Removed the `--no-browser` option, replaced with the `-u|--url` option
 
 ## [0.3.0][0.3.0] - 2025-06-24
 

src/nugraph/GraphCommand.cs

@@ -51,12 +51,16 @@ protected override async Task<int> ExecuteAsync(CommandContext commandContext, G
         if (graphUrl != null)
         {
             var url = graphUrl.ToString();
-            // Using "console.WriteLine(url)" (lowercase c) would insert newlines at the physical console length, making the written URL neither copyable nor clickable
-            // At that point the status has terminated so it's fine not using the IAnsiConsole methods
-            await stdOut.WriteLineAsync(url);
-            if (!settings.NoBrowser)
+            if (settings.UrlAction.HasFlag(UrlAction.print))
+            {
+                // Using "console.WriteLine(url)" (lowercase c) would insert newlines at the physical console length, making the written URL neither copyable nor clickable
+                // At that point the status has terminated so it's fine not using the IAnsiConsole methods
+                await stdOut.WriteLineAsync(url);
+            }
+            if (settings.UrlAction.HasFlag(UrlAction.open))
             {
                 Process.Start(new ProcessStartInfo(url) { UseShellExecute = true });
+                console.WriteLine($"The {source} dependency graph has been opened in the default browser");
             }
         }
         else if (settings.OutputFile != null)

src/nugraph/GraphCommandSettings.cs

@@ -12,6 +12,15 @@
 
 namespace nugraph;
 
+[Flags]
+[SuppressMessage("ReSharper", "InconsistentNaming", Justification = "Better fit for command line options")]
+public enum UrlAction
+{
+    none = 0,
+    open = 1 << 0,
+    print = 1 << 1,
+}
+
 [SuppressMessage("ReSharper", "AutoPropertyCanBeMadeGetOnly.Global", Justification = "Required for Spectre.Console.Cli binding")]
 [SuppressMessage("ReSharper", "UnusedAutoPropertyAccessor.Global", Justification = "Required for Spectre.Console.Cli binding")]
 [SuppressMessage("ReSharper", "ClassNeverInstantiated.Global", Justification = "Instantiated by Spectre.Console.Cli through reflection")]
@@ -21,66 +30,77 @@ internal sealed class GraphCommandSettings : CommandSettings
     public const string DefaultTitle = "Dependency graph of [SOURCE]";
 
     [CommandArgument(0, "[SOURCE]")]
-    [Description("The source of the graph. Can be either a directory containing a .NET project, a .NET project file (csproj/fsproj/vbproj) or the name of a NuGet package, " +
-                 "optionally with a specific version, e.g. [b]Newtonsoft.Json/13.0.3[/].")]
+    [Description("The source of the graph\n" +
+                 "Can be either\n" +
+                 "  * the name of a NuGet package, optionally with a specific version, e.g. [b]Newtonsoft.Json/13.0.3[/]\n" +
+                 "  * a .NET project file (csproj/fsproj/vbproj)\n" +
+                 "  * a directory containing a single .NET project\n")]
     public string? SourceInput { get; init; }
 
     public FileOrPackage? Source { get; private set; }
 
-    [CommandOption("-o|--output <OUTPUT>")]
-    [Description("The path to the dependency graph output file. If not specified, the dependency graph URL is written on the standard output and an online service is opened in the default browser.")]
-    public FileInfo? OutputFile { get; init; }
-
     [CommandOption("-f|--framework <FRAMEWORK>")]
-    [Description("The target framework to consider when building the dependency graph.")]
+    [Description("The target framework to consider when building the dependency graph\n" +
+                 "See https://learn.microsoft.com/en-us/dotnet/standard/frameworks#supported-target-frameworks for the list of supported target frameworks")]
     [TypeConverter(typeof(NuGetFrameworkConverter))]
     public NuGetFramework? Framework { get; init; }
 
     [CommandOption("-r|--runtime <RUNTIME_IDENTIFIER>")]
-    [Description("The target runtime to consider when building the dependency graph.")]
+    [Description("The target runtime to consider when building the dependency graph\n" +
+                 "See https://learn.microsoft.com/en-us/dotnet/core/rid-catalog#known-rids for the list of known runtime identifiers")]
     public string? RuntimeIdentifier { get; init; }
 
+    [CommandOption("-o|--output <OUTPUT>")]
+    [Description("The path to the dependency graph output file\n" +
+                 "A Mermaid diagram is written if the file name ends with either [b].mmd[/] or [b].mermaid[/], otherwise a Graphviz diagram is written\n" +
+                 "If not specified, the default web browser is used to render the dependency graph using an online service\n" +
+                 "See also the [b]--format[/] and [b]--url[/] options")]
+    public FileInfo? OutputFile { get; init; }
+
     [CommandOption("-m|--format <FORMAT>")]
-    [Description($"The format to use when the [b]--output[/] option is not specified.\n" +
+    [Description($"The format to use when the [b]--output[/] option is not specified\n" +
                  $"Use [b]mmd[/] or [b]mermaid[/] for Mermaid Live Editor https://mermaid.live\n" +
                  $"Use [b]dot[/], [b]gv[/] or [b]graphviz[/] for Edotor https://edotor.net\n" +
-                 "See https://github.com/0xced/nugraph/#output for even more supported formats.")]
+                 "See https://github.com/0xced/nugraph/#output for even more supported formats")]
     [DefaultValue("mermaid")]
     public string Format { get; init; } = "";
 
     public OnlineService Service { get; private set; }
 
+    [CommandOption("-u|--url")]
+    [Description("Defines what to do when the [b]--output[/] option is not specified\n" +
+                 "Use [b]open[/] (the default) for rendering the dependency graph using an online service or [b]print[/] for printing the graph URL on the standard output without opening the browser\n" +
+                 "Both options can be combined with a comma, i.e. [b]open,print[/] to both open the URL and print it")]
+    [DefaultValue(UrlAction.open)]
+    public UrlAction UrlAction { get; init; }
+
     [CommandOption("-d|--direction <GRAPH_DIRECTION>")]
-    [Description($"The direction of the dependency graph. Possible values are [b]{nameof(GraphDirection.LeftToRight)}[/] and [b]{nameof(GraphDirection.TopToBottom)}[/]")]
+    [Description($"The direction of the dependency graph, possible values are [b]{nameof(GraphDirection.LeftToRight)}[/] (recommended for large graphs) and [b]{nameof(GraphDirection.TopToBottom)}[/] (good for small graphs)")]
     [DefaultValue(GraphDirection.LeftToRight)]
     public GraphDirection GraphDirection { get; init; }
 
     [CommandOption("-t|--title <GRAPH_TITLE>")]
-    [Description("The title of the dependency graph.")]
+    [Description("The title of the dependency graph")]
     [DefaultValue(DefaultTitle)]
     public string Title { get; set; } = "";
 
     [CommandOption("-s|--include-version")]
-    [Description("Include package versions in the dependency graph. E.g. [b]Serilog/4.3.0[/] instead of [b]Serilog[/]")]
+    [Description("Include package versions in the dependency graph nodes, e.g. [b]Serilog/4.3.0[/] instead of [b]Serilog[/]")]
     [DefaultValue(false)]
     public bool GraphIncludeVersions { get; init; }
 
     [CommandOption("-i|--ignore <PACKAGE>")]
-    [Description("Packages to ignore in the dependency graph. Supports * wildcards. May be used multiple times.")]
+    [Description("Packages to ignore in the dependency graph, may be used multiple times and supports * wildcards, e.g. [b]--ignore \"System.*\"[/]")]
     public string[] GraphIgnore { get; init; } = [];
 
     [CommandOption("--no-links")]
-    [Description("Remove clickable links from the the dependency graph. Can be useful to reduce the size of the graph if you get \"Maximum text size in diagram exceeded\" in Mermaid Live Editor.")]
+    [Description("Remove clickable links from the the dependency graph\n" +
+                 "Can be useful to reduce the size of the graph if it becomes too large and Mermaid Live Editor is returning \"Maximum text size in diagram exceeded\" ")]
     [DefaultValue(false)]
     public bool NoLinks { get; set; }
 
-    [CommandOption("--no-browser")]
-    [Description("Do not open the default browser, only print the graph URL on the console when the [b]--output[/] option is not specified.")]
-    [DefaultValue(false)]
-    public bool NoBrowser { get; set; }
-
     [CommandOption("-l|--log <LEVEL>")]
-    [Description($"The NuGet operations log level. Possible values are [b]{nameof(LogLevel.Debug)}[/], [b]{nameof(LogLevel.Verbose)}[/], [b]{nameof(LogLevel.Information)}[/], [b]{nameof(LogLevel.Minimal)}[/], [b]{nameof(LogLevel.Warning)}[/] and [b]{nameof(LogLevel.Error)}[/]")]
+    [Description($"The NuGet operations log level, possible values are [b]{nameof(LogLevel.Debug)}[/], [b]{nameof(LogLevel.Verbose)}[/], [b]{nameof(LogLevel.Information)}[/], [b]{nameof(LogLevel.Minimal)}[/], [b]{nameof(LogLevel.Warning)}[/] and [b]{nameof(LogLevel.Error)}[/]")]
 #if DEBUG
     [DefaultValue(LogLevel.Debug)]
 #else
@@ -89,20 +109,20 @@ internal sealed class GraphCommandSettings : CommandSettings
     public LogLevel LogLevel { get; init; }
 
     [CommandOption("--nuget-root <PATH>", IsHidden = true)]
-    [Description("The NuGet root directory. Can be used to completely isolate nugraph from default NuGet operations.")]
+    [Description("The NuGet root directory, can be used to completely isolate nugraph from default NuGet operations")]
     public string? NuGetRoot { get; init; }
 
     [CommandOption("--sdk <PATH>", IsHidden = true)]
-    [Description("Path to the .NET SDK directory. E.g. [b]/usr/local/share/dotnet/sdk/8.0.410[/]")]
+    [Description("Path to the .NET SDK directory, e.g. [b]/usr/local/share/dotnet/sdk/8.0.410[/]")]
     public DirectoryInfo? Sdk { get; init; }
 
     [CommandOption("--include-ignored-packages", IsHidden = true)]
-    [Description("Include ignored packages in the dependency graph. Used for debugging.")]
+    [Description("Include ignored packages in the dependency graph, used for debugging")]
     [DefaultValue(false)]
     public bool GraphWriteIgnoredPackages { get; init; }
 
     [CommandOption("--diagnose", IsHidden = true)]
-    [Description("Prints diagnostics information.")]
+    [Description("Prints diagnostics information")]
     [DefaultValue(false)]
     public bool Diagnose { get; init; }
 

tests/nugraph.Tests/Nugraph.cs

@@ -5,7 +5,7 @@ namespace nugraph.Tests;
 
 public abstract class Nugraph
 {
-    public abstract Task<NugraphResult> RunAsync(string[] arguments, string? workingDirectory = null, LogLevel logLevel = LogLevel.Warning, bool noBrowser = true);
+    public abstract Task<NugraphResult> RunAsync(string[] arguments, string? workingDirectory = null, LogLevel logLevel = LogLevel.Warning, UrlAction action = UrlAction.print);
 
     public abstract string Version { get; }
 }

tests/nugraph.Tests/NugraphGlobalTool.cs

@@ -28,7 +28,7 @@ public NugraphGlobalTool()
 
     public override string Version => _version ?? "N/A";
 
-    public override async Task<NugraphResult> RunAsync(string[] arguments, string? workingDirectory = null, LogLevel logLevel = LogLevel.Warning, bool noBrowser = true)
+    public override async Task<NugraphResult> RunAsync(string[] arguments, string? workingDirectory = null, LogLevel logLevel = LogLevel.Warning, UrlAction action = UrlAction.print)
     {
         // https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools#install-a-global-tool
         var stdOut = new StringWriter { NewLine = "\n" };
@@ -44,10 +44,7 @@ public override async Task<NugraphResult> RunAsync(string[] arguments, string? w
                     args.Add(argument);
                 }
                 args.Add("--log").Add(logLevel.ToString());
-                if (noBrowser)
-                {
-                    args.Add("--no-browser");
-                }
+                args.Add("--url").Add(action.ToString());
             })
             .WithWorkingDirectory(workingDirectory ?? toolsDirectory)
             .WithStandardOutputPipe(PipeTarget.ToDelegate(stdOut.WriteLine))

tests/nugraph.Tests/NugraphProgram.cs

@@ -17,15 +17,15 @@ public NugraphProgram()
         Version = SemanticVersion.Parse(version).ToNormalizedString();
     }
 
-    public override async Task<NugraphResult> RunAsync(string[] arguments, string? workingDirectory = null, LogLevel logLevel = LogLevel.Warning, bool noBrowser = true)
+    public override async Task<NugraphResult> RunAsync(string[] arguments, string? workingDirectory = null, LogLevel logLevel = LogLevel.Warning, UrlAction action = UrlAction.print)
     {
         using var consoleOut = new TestConsole();
         consoleOut.Profile.Width = 256;
         using var consoleErr = new TestConsole();
         consoleErr.Profile.Width = 256;
         await using var stdOut = new StringWriter();
         var program = new Program(new DirectoryInfo(workingDirectory ?? Environment.CurrentDirectory), consoleOut, consoleErr, stdOut);
-        var args = arguments.Append("--log").Append(logLevel.ToString()).Append("--no-browser").Append(noBrowser.ToString()).ToArray();
+        var args = arguments.Append("--log").Append(logLevel.ToString()).Append("--url").Append(action.ToString()).ToArray();
         var exitCode = await program.RunAsync(args);
         return new NugraphResult(exitCode, GetOutput(consoleOut, stdOut), GetOutput(consoleErr, null));
     }