Skip to content
XrmGhost Docs

Getting Started with the CLI

Getting Started with the CLI

Section titled “Getting Started with the CLI”

The xrmghost CLI (invoked as xg) is the primary way to run Dataverse plugins, manage environments, and interact with the XrmGhost ecosystem from a terminal.

This guide covers installing the CLI, then orienting yourself — how to explore available commands, confirm your setup, and find your way into the main workflows.

Install the CLI

Section titled “Install the CLI”

On your development machine, install with winget:

Terminal window
winget install XrmGhost.Cli

It installs the signed xg.exe and, in the bin\ folder next to it, the signed host that executes your plugins — there is no separate host download. Open a new shell afterwards so the updated PATH is picked up. The publisher to expect and how to verify the signature, including WDAC policies, are in Trust and WDAC.

In CI only, install the .NET global tool from NuGet: dotnet tool install --global XrmGhost.Cli. It is meant for build agents and automation, not for a desktop. It needs the .NET 9 runtime and does not carry the host: the pipeline installs it with xg init --no-interactive, as shown in Run in CI.

Last option: without winget, download xrmghost-cli-<version>-full.zip from GitHub Releases, extract it to a folder of its own keeping xg.exe and bin\ together, and add that folder — not bin\ — to your user PATH.

Then, with winget or the ZIP, prepare the machine before your first xg run:

Terminal window
xg init

xg init checks Windows and .NET Framework 4.7.2, resolves the host — the one in the bin\ folder next to xg.exe takes precedence — installs it into the managed root only if no usable host is found, and tells you the next step. It exits 0 when the host is healthy or repaired, 1 when the setup cannot be repaired.

To update:

  • winget — winget upgrade XrmGhost.Cli; xg.exe and bin\ are replaced together.
  • ZIP — download a newer -full.zip and extract it over the same folder: xg.exe and bin\ move together. Neither xg doctor --fix nor xg setup host updates the host in bin\.
  • Global tool in CI — dotnet tool update --global XrmGhost.Cli.

Coming from the .NET global tool on your desktop? The old installation left an xg shim in %USERPROFILE%\.dotnet\tools, and xg init warns when it finds it. Run Get-Command xg -All (or where xg from cmd): if a line points to .dotnet\tools, remove it with dotnet tool uninstall --global XrmGhost.Cli, or put the winget or ZIP folder before it in PATH. The first line must be the signed xg.exe, so that only one xg answers.

Alpha builds are not signed and may be blocked by Smart App Control.

The full walkthrough, with prerequisites, is in Getting Started.

Run in CI

Section titled “Run in CI”

On a build agent, install the global tool from NuGet and turn prompts off. Run xg init --no-interactive first, then xg run --no-interactive:

Terminal window
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 starts an interactive sign-in. xg init --no-interactive installs the host into the managed root (%LOCALAPPDATA%\xrmghost\framework-host\) when the agent has none. xg run --no-interactive does not download the host: if no usable host is found, it exits with a non-zero code and tells you to run xg init --no-interactive. The agent must be Windows: the host is a .NET Framework 4.7.2 process.

Confirm the CLI is available

Section titled “Confirm the CLI is available”

Once the binary is in place, verify it responds:

Terminal window
xg --version

You should see a version header showing the CLI version and the version of the bundled Framework Host. If the command is not found, make sure the folder that contains xg.exe is on your PATH and that you opened a new shell after changing it.

Discover available commands

Section titled “Discover available commands”

The fastest way to understand what the CLI can do is to ask it:

Terminal window
xg --help

This prints the top-level command tree. For any command or subcommand, you can append --help to drill deeper:

Terminal window
xg env --help
xg license --help
xg run --help

The --help surface is always up to date with the installed version, so it is the most reliable reference while you orient yourself.

Main command areas

Section titled “Main command areas”

The CLI organises its functionality into the following top-level areas:

CommandPurpose
initPrepare the machine to run plugins: check the prerequisites and resolve or repair the host
runExecute a Dataverse plugin using a scenario file
generate-scenarioCreate a template JSON scenario file for a plugin
envAdd, list, switch between, and manage environment configurations
licenseActivate a license, check status, and retrieve your machine ID
doctorRun health checks to diagnose configuration or connectivity issues; --fix repairs the managed host
privacyDisplay information about data collected by the tool
setup hostAdvanced: install or update the host in the managed install root only

These areas are stable entry points. Each has its own --help page.

A safe first exploration path

Section titled “A safe first exploration path”

If you are new to the CLI, the following sequence lets you explore without making any changes:

  1. Check your license status — understand what tier and features are available to you:

    Terminal window
    xg license status

  2. List configured environments — see what Dataverse environments (if any) are already set up:

    Terminal window
    xg env list

  3. Run diagnostics — confirm connectivity and configuration are healthy (without --fix, doctor only reads):

    Terminal window
    xg doctor

    Use --verbose for detailed diagnostic output:

    Terminal window
    xg doctor --verbose

None of the commands above modify state. They are read-only discovery steps. To repair the setup, use xg init or xg doctor --fix.

When you are ready to act

Section titled “When you are ready to act”

Once you are oriented, typical next actions are:

  • Add an environment — use xg env add to start the interactive wizard for connecting a Dataverse environment.
  • Generate a scenario file — use xg generate-scenario to create a JSON template for the plugin you want to test.
  • Run a plugin — once a scenario file is prepared and an environment is active, use xg run to execute the plugin out-of-process.

Getting detailed command reference

Section titled “Getting detailed command reference”

Reference documentation for every command, flag, and option is under the CLI Reference section. xg <command> --help always reflects the installed version.

Next steps

Section titled “Next steps”