NovaModuleTools
Menu Getting Started

Tutorial

Install NovaModuleTools and prove the workflow works

This quickstart is optimized for first success. You will install the module, choose the right entrypoint, scaffold the packaged example, build it, test it, import the built module, and run a working command.

1. Prerequisites

You need:

  • PowerShell 7.4 or newer
  • permission to install modules from PowerShell Gallery
  • Git if you plan to use Git-driven version bumping later

You do not need to understand the entire tool before starting. The example-based path below is designed to show you a complete working project quickly.

2. Install the module

Install NovaModuleTools from PowerShell Gallery and import it into the current session:

PS> Install-Module -Name NovaModuleTools
PS> Import-Module NovaModuleTools

PowerShell only: module installation and import happen in PowerShell, even if you plan to use the standalone command-line launcher later.

After import, you can use the PowerShell cmdlets directly.

Expected result: commands such as Get-NovaProjectInfo and Invoke-NovaBuild resolve in your PowerShell session.

3. Choose PowerShell or CLI entrypoints

Nova supports two normal ways of working:

Mode Use it when… How it works
PowerShell cmdlets in pwsh You are already inside pwsh. Import the module once, then use cmdlets directly.
Standalone nova launcher You want to run Nova from zsh or bash on macOS/Linux. Install the launcher once with Install-NovaCli before you expect nova to resolve in your shell.

Install the standalone launcher on macOS/Linux

PS> Install-NovaCli

By default, the launcher is installed to ~/.local/bin/nova. If that directory is not already on PATH, add it to your shell profile:

% echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
% source ~/.zshrc

On Windows, keep using the PowerShell cmdlets after you import the module. Install-NovaCli is intentionally for macOS/Linux only.

4. Scaffold the packaged example

The fastest way to understand Nova is to start from the packaged example, because it already contains a real public command, a private helper, a resource file, tests, and a complete project.json.

Scaffold the packaged example

Showing: PowerShell 

PS> Initialize-NovaModule -Example -Path ~/Work

Nova asks for the project name, description, version, author, minimum PowerShell version, whether Git should be initialized, and whether Nova should add the optional Agentic Copilot starter package.

The starting version prompt now defaults to 0.1.0-preview, so new projects begin on Nova's prerelease-friendly starter line unless you choose a different version. Before the first question, Nova also checks whether a newer NovaModuleTools release is available and warns without blocking the scaffold flow. When you enable Git, Nova also creates or updates a default .gitignore in the new project root so common local and CI artifact paths start ignored without overwriting existing ignore rules.

The Agentic package follows Nova's maintained agentic guidance through a filtered starter mirror, including Nova build/test/package expectations, project.json Manifest.PowerShellHostVersion compatibility guidance, strict ScriptAnalyzer guidance without excluded rules, generated dist module files, command-help ownership, source-mirrored test guidance, instructions to fix ScriptAnalyzer findings reported by run.ps1 before handoff, explicit public/private PowerShell file ownership guidance, a best-effort source/helper-script maintainability guidance plus separate test-design guidance delivered through Agentic Copilot guidance files, explicit PSScriptAnalyzer workflow guidance for ./scripts/build/Invoke-ScriptAnalyzerCI.ps1, ./run.ps1, and focused Invoke-ScriptAnalyzer usage, separate Invoke-NovaTest unit-test and Test-NovaBuild build-validation guidance that forbids direct Invoke-Pester, explicit valid-PlatyPS help guidance for docs/<ProjectName>/en-US/*.md using New-MarkdownCommandHelp, Update-MarkdownCommandHelp, and Test-MarkdownCommandHelp, with a matching help file required for every new public entry point, and a strict file-ending rule for changed or generated text files.

Nova then creates a project folder under the path you selected.

The generated project.json also starts with Nova's standard Pester defaults, including explicit source coverage paths for src/public/, nested src/private/ helper folders, and src/classes/, JaCoCo output in artifacts/coverage.xml, and a 90 percent target. The minimal scaffold keeps that CodeCoverage block opt-in with Enabled=false, while the packaged example scaffold enables coverage by default so Test-NovaBuild measures src/**/*.ps1 before any build step.

If you enable the Agentic package, Nova also asks for a short project name used in generated guidance placeholders such as Invoke-<ShortName>*. For NovaModuleTools the short name is Nova, but it could also have been NMT.

Expected result: a new project folder that contains src/, tests/, docs/, and project.json.

5. Build and test the example

Change into the newly created project and run the normal build and test flow:

Build and test the project

Showing: PowerShell 

PS> Set-Location ~/Work/<YourProjectName>
PS> Invoke-NovaBuild
PS> Invoke-NovaTest
PS> Test-NovaBuild

Expected result:

  • the built module is written to dist/<ProjectName>/
  • unit-test and build-validation workflows both complete successfully
  • the test run writes results to artifacts/TestResults.xml

The scaffold keeps code coverage opt-in. When you later set Pester.CodeCoverage.Enabled to true, the same Nova test flow also writes artifacts/coverage.xml and stops when the measured coverage percentage is lower than the configured CoveragePercentTarget.

6. Run the example command from the built or locally published module

Now take the generated module into the environment you want to use and run the example command.

Use the built module

Showing: PowerShell 

PS> $project = Get-NovaProjectInfo
PS> Import-Module $project.OutputModuleDir -Force
PS> Get-ExampleGreeting
PS> Get-ExampleGreeting -Name 'Nova user' -AsObject

PowerShell only: this path imports the module directly from dist/ and then runs the exported example command in the current PowerShell session.

Expected result: in PowerShell mode, the first call returns the example greeting text and the second call returns a structured object form. In command-line mode, local publish completes successfully and the two pwsh one-liners return the same text and structured object output from the published module.

This is the key Nova habit: you work with the built output in dist/, not loose source files, because that matches what will eventually be packaged or published. Local publish is useful when you specifically want the installed-module experience instead of the direct dist/ import loop.

7. Start from the minimal scaffold instead

Use the minimal scaffold when you already understand the Nova project shape and want a clean starting point rather than the full working example.

Start from the minimal scaffold

Showing: PowerShell 

PS> Initialize-NovaModule -Path ~/Work

The minimal scaffold still asks for the same core project metadata, including the optional Agentic Copilot setup question and the follow-up short-name prompt when you answer Yes, but it gives you a smaller starter layout than the example project. When enabled, the Agentic package uses the same filtered starter mirror as the example scaffold.

Use the example scaffold when you want the fastest learning path. Use the minimal scaffold when you want the leanest new project.

8. Next steps

Continue to Core Workflows Explore project.json settings

After the quickstart, most developers need one of these pages next: