#215 feat: enhance Invoke-NovaCli command handling with improved help and error messages

refactor(Invoke-NovaCli): align with terminal-ux-design principles
Fixes #222

Author: stiwicourage

CHANGELOG.md

@@ -24,6 +24,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `Install-NovaCli` now prints the installed launcher path, suggests the next command to run, and gives a clearer `PATH` warning when the destination directory is not yet available from the shell.
 - `Invoke-NovaAgenticCopilotScaffold` now shows apply progress, ends with the project root plus suggested review and validation steps, and fails with clearer cancellation guidance when the overwrite warning is declined.
 - `Invoke-NovaBuild` now shows progress for the main build phases, ends with the output module directory plus the next suggested validation step, and explains the refreshed session when `-ContinuousIntegration` reloads the built module.
+- `Invoke-NovaCli` now treats blank command input as root help, reports unknown commands with clearer recovery guidance, and ships a dedicated PlatyPS help topic for the PowerShell wrapper surface.
 
 ### Deprecated
 

RELEASE_NOTE.md

@@ -20,6 +20,7 @@ This file summarizes the release notes for NovaModuleTools. **UNRELEASED** chang
 - `Install-NovaCli` now prints the installed launcher path, suggests the next command to run, and gives a clearer `PATH` warning when the launcher directory is not yet available from the shell.
 - `Invoke-NovaAgenticCopilotScaffold` now shows apply progress, ends with the project root plus suggested review and validation steps, and gives clearer cancellation guidance when the overwrite warning is declined.
 - `Invoke-NovaBuild` now shows progress for the main build phases, ends with the output module directory plus the next suggested validation step, and explains the refreshed session when `-ContinuousIntegration` reloads the built module.
+- `Invoke-NovaCli` now treats blank command input as root help, reports unknown commands with clearer recovery guidance, and ships a dedicated help topic for the PowerShell wrapper surface.
 
 ### Deprecated
 

docs/NovaModuleTools/en-US/Invoke-NovaCli.md

@@ -0,0 +1,191 @@
+---
+document type: cmdlet
+external help file: NovaModuleTools-Help.xml
+HelpUri: ''
+Locale: en-US
+Module Name: NovaModuleTools
+ms.date: 05/24/2026
+PlatyPS schema version: 2024-05-01
+title: Invoke-NovaCli
+---
+
+# Invoke-NovaCli
+
+## SYNOPSIS
+
+Runs Nova's launcher-style command routing from PowerShell.
+
+## SYNTAX
+
+### __AllParameterSets
+
+```text
+PS> Invoke-NovaCli [[-Command] <string>] [[-Arguments] <string[]>] [-WhatIf] [-Confirm] [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+`Invoke-NovaCli` is the PowerShell entrypoint behind the launcher-style `nova <command>` workflow.
+
+Use this cmdlet when you want Nova's routed CLI experience from inside PowerShell, including root help, per-command help, and the routed command surfaces such as `build`, `test`, `package`, `publish`, `release`, `update`, and `notification`.
+
+When `-Command` is omitted or blank, Nova falls back to the root CLI help.
+
+This cmdlet forwards `-WhatIf` and `-Confirm` semantics to the routed command surface instead of treating `Invoke-NovaCli` itself as the mutating operation owner.
+
+Use `Get-Help Invoke-NovaCli -Full` when you want the PowerShell wrapper help. Use `nova --help`, `nova <command> --help`, or `nova --help <command>` when you want launcher-native CLI help.
+
+## EXAMPLES
+
+### EXAMPLE 1
+
+```text
+PS> Invoke-NovaCli
+```
+
+Shows the root Nova CLI help.
+
+### EXAMPLE 2
+
+```text
+PS> Invoke-NovaCli build --help
+```
+
+Shows the short help for the routed `build` command by using launcher-style arguments from PowerShell.
+
+### EXAMPLE 3
+
+```text
+PS> Invoke-NovaCli --help build
+```
+
+Shows the long help for the routed `build` command.
+
+### EXAMPLE 4
+
+```text
+PS> Invoke-NovaCli publish --repository PSGallery --api-key <key> -WhatIf
+```
+
+Previews the routed publish workflow without changing files or publishing artifacts.
+
+## PARAMETERS
+
+### -Arguments
+
+Pass the remaining launcher-style arguments for the routed command.
+
+Use CLI syntax here, for example `--help`, `--verbose`, `--what-if`, or route-specific flags such as `--repository`.
+
+```yaml
+Type: System.String[]
+DefaultValue: ''
+SupportsWildcards: false
+Aliases: []
+ParameterSets:
+  - Name: (All)
+    Position: 1
+    IsRequired: false
+    ValueFromPipeline: false
+    ValueFromPipelineByPropertyName: false
+    ValueFromRemainingArguments: true
+DontShow: false
+AcceptedValues: []
+HelpMessage: ''
+```
+
+### -Command
+
+Choose the routed Nova command to run, for example `build`, `test`, `package`, `publish`, `release`, `notification`, `update`, or the root help/version forms such as `--help` and `--version`.
+
+When this parameter is omitted or blank, Nova shows the root CLI help.
+
+```yaml
+Type: System.String
+DefaultValue: ''
+SupportsWildcards: false
+Aliases: []
+ParameterSets:
+  - Name: (All)
+    Position: 0
+    IsRequired: false
+    ValueFromPipeline: false
+    ValueFromPipelineByPropertyName: false
+    ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: []
+HelpMessage: ''
+```
+
+### -Confirm
+
+Forward confirmation behavior to routed mutating commands that support Nova's CLI confirmation flow.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+DefaultValue: ''
+SupportsWildcards: false
+Aliases:
+  - cf
+ParameterSets:
+  - Name: (All)
+    Position: Named
+    IsRequired: false
+    ValueFromPipeline: false
+    ValueFromPipelineByPropertyName: false
+    ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: []
+HelpMessage: ''
+```
+
+### -WhatIf
+
+Forward preview behavior to routed commands that support Nova's non-destructive preview flow.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+DefaultValue: ''
+SupportsWildcards: false
+Aliases:
+  - wi
+ParameterSets:
+  - Name: (All)
+    Position: Named
+    IsRequired: false
+    ValueFromPipeline: false
+    ValueFromPipelineByPropertyName: false
+    ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: []
+HelpMessage: ''
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### None
+
+You can't pipe objects to this cmdlet.
+
+## OUTPUTS
+
+### System.Object
+
+This cmdlet returns the routed command result or CLI help text for help and version requests.
+
+## NOTES
+
+`Invoke-NovaCli` is a PowerShell wrapper around Nova's launcher-style command routing. The routed command surfaces keep CLI syntax such as `--help`, `--verbose`, and `--what-if`.
+
+Use `Ctrl+C` if you need to cancel a running routed workflow.
+
+## RELATED LINKS
+
+- [Invoke-NovaBuild](./Invoke-NovaBuild.md)
+- [Test-NovaBuild](./Test-NovaBuild.md)
+- [Install-NovaCli](./Install-NovaCli.md)
+- [NovaModuleTools Module](./NovaModuleTools.md)

docs/NovaModuleTools/en-US/NovaModuleTools.md

@@ -32,6 +32,10 @@ Shows whether prerelease update notifications are enabled. Stable release notifi
 
 Installs the bundled command-line launcher into a user command directory on macOS or Linux.
 
+### `PS> Invoke-NovaCli`
+
+Runs Nova's launcher-style command routing from inside PowerShell.
+
 ### `PS> Invoke-NovaBuild`
 
 Builds the current NovaModuleTools project into a ready-to-import PowerShell module.

src/private/cli/InvokeNovaCliCommandRoute.ps1

@@ -216,7 +216,7 @@ function Invoke-NovaCliCommandRoute {
             return Get-NovaCliHelp
         }
         default {
-            Stop-NovaOperation -Message "Unknown command: <$command> | Use 'nova --help' to see available commands." -ErrorId 'Nova.Validation.UnknownCliCommand' -Category InvalidArgument -TargetObject $command
+            Stop-NovaOperation -Message "Unknown nova command: $command. Run 'nova --help' to list available commands, or 'nova --help <command>' for command-specific help." -ErrorId 'Nova.Validation.UnknownCliCommand' -Category InvalidArgument -TargetObject $command
         }
     }
 }

src/public/InvokeNovaCli.ps1

@@ -8,8 +8,14 @@ function Invoke-NovaCli {
         [string[]]$Arguments
     )
 
+    $commandName = if ([string]::IsNullOrWhiteSpace($Command)) {
+        '--help'
+    } else {
+        $Command
+    }
+
     $invocationRequest = [pscustomobject]@{
-        Command = $Command
+        Command = $commandName
         BoundParameters = $PSBoundParameters
         Arguments = $Arguments
     }

tests/private/cli/InvokeNovaCliCommandRoute.Tests.ps1

@@ -231,6 +231,16 @@ Describe 'Invoke-NovaCliCommandRoute' {
 
     It 'throws on unknown command' {
         Mock Confirm-NovaCliRoutedCommand {}
-        {Invoke-NovaCliCommandRoute -InvocationContext (New-TestContext -Command 'bogus')} | Should -Throw -ErrorId 'Nova.Validation.UnknownCliCommand'
+        $record = $null
+
+        try {
+            Invoke-NovaCliCommandRoute -InvocationContext (New-TestContext -Command 'bogus')
+        } catch {
+            $record = $_
+        }
+
+        $record | Should -Not -BeNullOrEmpty
+        $record.FullyQualifiedErrorId | Should -Be 'Nova.Validation.UnknownCliCommand'
+        $record.Exception.Message | Should -Be "Unknown nova command: bogus. Run 'nova --help' to list available commands, or 'nova --help <command>' for command-specific help."
     }
 }

tests/public/InvokeNovaCli.Tests.ps1

@@ -14,6 +14,10 @@ Describe 'Invoke-NovaCli' {
         (Invoke-NovaCli).Command | Should -Be '--help'
     }
 
+    It 'defaults blank command input to --help' {
+        (Invoke-NovaCli '').Command | Should -Be '--help'
+    }
+
     It 'forwards command and remaining arguments to the invocation context' {
         Invoke-NovaCli 'build' '--ci' '--override-warning' | Out-Null
         $script:request.Command | Should -Be 'build'