Getting Started

Getting Started

XrmGhost runs your Dynamics plugins and tests on your machine. This page takes you from nothing installed to a first local run.

It’s three steps: install the CLI, run xg init, run xg run.

Prerequisites

XrmGhost runs on Windows x64. What you need depends on how you install:

Channel	Use it for	Requirement	Why
winget — recommended	Your development machine	.NET Framework 4.7.2	Installs the signed, self-contained xg.exe together with the host that executes your plugins, matching the Dataverse server-side runtime. No .NET runtime is needed for the CLI itself.
.NET global tool — CI only	Build agents and automation	.NET 9 runtime and .NET Framework 4.7.2	The global tool runs xg on the shared .NET 9 runtime; the host still needs 4.7.2.
Signed ZIP	Machines without winget	.NET Framework 4.7.2	The same signed bundle winget installs, downloaded by hand.

On Windows 10/11 the 4.7.2 framework is almost always already there; on a clean build agent it may not be. xg init checks it for you. For the global tool, check for the .NET 9 runtime with dotnet --list-runtimes and look for a Microsoft.NETCore.App 9.x line.

1. Install the CLI

Install with winget

On your development machine, install with the Windows Package Manager:

winget install XrmGhost.Cli

This installs the signed xg.exe and, in the bin\ folder next to it, the signed host that executes your plugins: there is nothing separate to download. winget adds the install folder to your PATH; open a new shell, so the new PATH is picked up, and confirm:

xg --version

Then prepare the machine with xg init before your first xg run.

To update later:

winget upgrade XrmGhost.Cli

winget replaces xg.exe and the host in bin\ together.

The publisher to expect and how to verify the signature (including WDAC policies) are described in Trust and WDAC.

In CI only: the .NET global tool

On build agents and in automation, install the XrmGhost.Cli package from NuGet as a .NET global tool:

dotnet tool install --global XrmGhost.Cli

This channel is for CI and automation only — on a desktop, use winget. The package does not carry the host, so the pipeline installs it with xg init --no-interactive before running anything:

dotnet tool install --global XrmGhost.Cli
xg init --no-interactive
xg run --no-interactive -a .\bin\Release\MyPlugins.dll -t MyPlugins.AccountPreCreate -s .\scenarios\account-create.json

None of these commands prompts or opens an interactive sign-in. xg init --no-interactive installs the host from the public release page into %LOCALAPPDATA%\xrmghost\framework-host\ when the agent has none — that is what it is for. xg run --no-interactive never downloads the host: if no usable host is found, it stops with a non-zero exit code and points to xg init --no-interactive. init reports the channel as dotnet tool: the global tool is the supported channel for CI, and init does not warn about it. The agent must be Windows, because the host is a .NET Framework 4.7.2 process.

The host is installed once and cached in that folder: later runs on the same agent reuse it. On an ephemeral agent the folder is empty at every run, so each xg init --no-interactive installs the latest stable host. To pin the host version between runs, cache %LOCALAPPDATA%\xrmghost\framework-host\ in your pipeline (for example with your CI’s cache step).

To update the CLI on an agent that keeps its tools between runs:

dotnet tool update --global XrmGhost.Cli

Last option: download the signed ZIP

If winget is not available, download the same bundle by hand from the public repository’s release page: github.com/xrmghost/xrmghost/releases. Pick the asset named xrmghost-cli-<version>-full.zip: it carries both xg.exe and the host. Before extracting, check who signed it, as described in Trust and WDAC.

Extract the ZIP to a folder of its own, for example C:\Tools\XrmGhost. The layout is:

C:\Tools\XrmGhost\
├── xg.exe      the CLI
└── bin\        the signed host that executes your plugins

Add the folder that contains xg.exe — C:\Tools\XrmGhost, not bin\ — to your user PATH (Settings → System → About → Advanced system settings → Environment Variables), open a new shell and run xg --version, then xg init before your first xg run.

To update later, download the newer xrmghost-cli-<version>-full.zip and extract it over the same folder: xg.exe and bin\ move together. The host in bin\ is updated only this way — neither xg doctor --fix nor xg setup host changes it, because both work on a separate, managed install that the bundled host takes precedence over.

Moving a desktop off the global tool

If you previously installed XrmGhost on your desktop with dotnet tool install -g XrmGhost.Cli, that installation left an xg shim in %USERPROFILE%\.dotnet\tools, which is on your PATH too. Two xg commands on the PATH means the one that runs depends on the order of the entries — and you may end up running a CLI older than the one you installed. xg init warns when it finds the shim. Find every xg your shell can see:

Get-Command xg -All | Select-Object Source

(from cmd, where xg gives the same list). If a line points to .dotnet\tools, remove the old shim:

dotnet tool uninstall -g XrmGhost.Cli

If you need to keep the global tool installed for now, make sure the winget or ZIP folder comes before %USERPROFILE%\.dotnet\tools in your PATH. Either way, open a new shell and run Get-Command xg -All again: the first line must be the signed xg.exe.

Alpha builds are not signed. Prereleases are not code-signed, so Windows Smart App Control may block them. Use them only if you need a fix before it reaches a stable release.

2. Run xg init

The CLI is light. The component that actually executes your plugins is the host — a .NET Framework 4.7.2 process that mirrors the Dataverse server-side runtime. xg init prepares the machine to run it:

xg init

It reports which xg is running and from which channel, checks Windows and .NET Framework 4.7.2, and resolves the host. With winget or the ZIP, the signed host is already in the bin\ folder next to xg.exe, and xg uses that host before any other installation it finds; init uses it as is. If no usable host is found — as with the global tool in CI — init installs the latest one into the managed install root (%LOCALAPPDATA%\xrmghost\framework-host\). It ends with the one next step that applies to you — activate a license with xg license activate, register an environment with xg env add, or start running plugins.

init exits 0 when the host is healthy or has been repaired, and 1 when the setup is in a state it cannot repair — the message says what to do. The details are in the xg init reference. To check the setup later without changing anything, run xg doctor; xg doctor --verbose also prints the resolved host path.

3. Run

With CLI and host in place, you’re ready. From a project that contains your plugins:

xg run -a .\bin\Debug\MyPlugins.dll -t MyPlugins.AccountPreCreate

The full set of options is in the xg run reference; the CLI Reference is the full map of commands. In CI, use xg init --no-interactive and xg run --no-interactive as shown in In CI only: the .NET global tool.

Where to go next

• Overview — the product-level introduction to XrmGhost.
• How It Works — the public explanation of the local-first execution model.
• Editions — see how Standard and Pro differ and which one fits your needs.
• CLI Reference — every command, flag, and what it does.
• Attributes — how you mark up plugins and scenarios for XrmGhost to pick up.
• Architecture — how the CLI, host, and Dataverse runtime fit together.
• Community — report bugs, request features, and open discussions.
• Contributing — working on XrmGhost itself.