CLI

XrmGhost CLI

The XrmGhost CLI (xg) is the primary developer interface for the XrmGhost ecosystem. On a development machine you install it with winget (winget install XrmGhost.Cli); in CI it is the XrmGhost.Cli .NET global tool from NuGet; without winget, the signed xrmghost-cli-<version>-full.zip from GitHub Releases carries the same bundle. Run xg init once before your first xg run. It gives you terminal access to the main workflows: executing Dataverse plugins out-of-process, managing environment configurations, handling licensing, and diagnosing problems.

Who the CLI Is For

The CLI is aimed at developers who:

• write and test Dataverse plugins locally before deploying to a Power Platform environment
• need scriptable, repeatable runs as part of a CI workflow
• prefer an AI-agent-first workflow or a terminal-first experience over a GUI

What the CLI Does

Command group	Purpose
init	Prepare the machine to run plugins — the first command after extracting the ZIP. Checks the prerequisites, resolves or repairs the Framework Host, and names the next step
run	Execute a Dataverse plugin using a scenario file, with the Framework Host running in the background
generate-scenario	Create a template scenario JSON for a given plugin, ready to pass to run
env	Add, edit, delete, list, activate, and switch Dataverse environment configurations
license	Activate your license, view its status and tier, and retrieve your machine’s platform ID
doctor	Run environment and configuration health checks to diagnose connectivity or setup issues; read-only unless --fix
privacy	Display information about telemetry data collection and local storage
setup host	Advanced: install or update the Framework Host in the managed install root

run uses the Framework Host bundled in the bin\ folder next to xg.exe first, then the managed install root, then legacy locations; when none is found, it points to xg init. Because the bundled host takes precedence, setup host and doctor --fix do not change the host of a winget or ZIP install: update it with winget upgrade XrmGhost.Cli or by extracting a newer ZIP.

For the full flag-level detail of every command and sub-command, see the CLI Reference section.

Output in CI and AI Agents

xg adapts its output to where stdout goes. In an interactive terminal (TTY) you get colours, clickable links, and output sized to the terminal window. When stdout is redirected — piped into another command, written to a file, captured by a CI runner or read by an AI agent — xg switches to a plain-text policy so that logs stay clean and parseable.

What changes when stdout is redirected

• No ANSI escape sequences. Colour is disabled unless you force it (see below), so log files and agent transcripts contain no \e[...m codes.
• No OSC 8 hyperlinks. Links are printed as plain text, never wrapped in terminal hyperlink sequences. This holds even when colour is forced.
• Predictable width. Output is laid out to the value of COLUMNS when it is an integer between 1 and 1000; if COLUMNS is unset, not an integer, or out of that range, the width is 240.

On a TTY, the width always follows the real terminal size: COLUMNS has no effect there.

Environment variables

Variable	Effect
NO_COLOR	When set to any non-empty value, disables colour everywhere — redirected output and TTY. It always wins over XRMGHOST_COLOR and FORCE_COLOR.
XRMGHOST_COLOR	When set to 1, forces ANSI colour in redirected output.
FORCE_COLOR	When set to a non-empty value other than 0, forces ANSI colour in redirected output.
COLUMNS	In redirected output only, sets the width when it is an integer from 1 to 1000; otherwise the width is 240.

XRMGHOST_COLOR and FORCE_COLOR re-enable ANSI colour only: they never re-enable OSC 8 links in redirected output.

Examples

Clean, uncoloured logs in CI or for an agent — the default, nothing to set:

xg doctor > doctor.log

Narrower output for a tool that reads fixed-width text:

COLUMNS=120 xg env list | tee env.txt

Coloured output in a CI log viewer that renders ANSI (links stay plain text):

XRMGHOST_COLOR=1 xg run --help | cat

Guaranteed plain text, even if the runner sets FORCE_COLOR for you:

NO_COLOR=1 FORCE_COLOR=1 xg doctor | cat   # NO_COLOR wins: no colour

How This Documentation Slice Is Organised

Page	What you will find
This page	Overview, orientation, and navigation
Getting Started	Download, xg init, and your first command
Reference section	CLI explanation and flags details

Where to Go Next

• New to XrmGhost? Start with Getting Started to download the ZIP, run xg init, and run your first plugin scenario.
• Looking for a specific flag or option? Go to CLI Reference for the per-command reference.
• Found a bug or missing capability? Use Community to report it or discuss it.
• Want to contribute? See Contributing for guidelines on updating narrative docs or the generation pipeline.