xg env import

xg env import

Import environment configurations from a JSON file into the local XrmGhost environment store. Supports both a single environment object and a bulk import file (array wrapped in an environments key). When an imported environment already exists by FriendlyName, the command interactively prompts to Skip or Overwrite the conflict.

License requirement: env import requires a Pro license tier. Run xg license status to verify your tier.

---

Synopsis

xg env import <FILE_PATH>

---

Arguments

Argument	Required	Description
<FILE_PATH>	Yes	Path to the JSON file containing the environment configuration(s) to import.

---

Options

env import has no optional flags beyond the required positional argument above. Global options (e.g. --help) apply as normal.

Flag	Type	Default	Description
--help	bool	false	Display help text for this command and exit.

---

Input File Format

The command accepts two JSON shapes:

Single environment object

{
  "FriendlyName": "My Dev Environment",
  "EnvironmentUrl": "https://myorg.crm.dynamics.com",
  "AuthenticationMethod": "ClientSecret",
  "ClientId": "00000000-0000-0000-0000-000000000001",
  "MetadataCacheLifecycle": "7.00:00:00"
}

Bulk import file (array wrapped in environments)

{
  "environments": [
    {
      "FriendlyName": "Dev",
      "EnvironmentUrl": "https://dev.crm.dynamics.com",
      "AuthenticationMethod": "ClientSecret",
      "ClientId": "00000000-0000-0000-0000-000000000001",
      "MetadataCacheLifecycle": "7.00:00:00"
    },
    {
      "FriendlyName": "QA",
      "EnvironmentUrl": "https://qa.crm.dynamics.com",
      "AuthenticationMethod": "ClientSecret",
      "ClientId": "00000000-0000-0000-0000-000000000002",
      "MetadataCacheLifecycle": "7.00:00:00"
    }
  ]
}

Client secret handling: The ClientSecret field is deliberately excluded from files produced by xg env export (it is marked [JsonIgnore] during export). If the import file does not contain a ClientSecret and the environment uses ClientSecret authentication, the command will interactively prompt you to enter it. To automate imports, pre-populate the field in the JSON before running the command in a non-interactive context.

Tenant (TenantId)

The import never reads a TenantId field from the file, even when the file was produced by xg env export: any TenantId value in the JSON is ignored.

• New environments go through the same unauthenticated, best-effort tenant probe used by xg env add ({EnvironmentUrl}/api/data/v9.2/WhoAmI, tenant read from authorization_uri in the WWW-Authenticate header). The probe needs HTTP reachability but no credentials; if it fails or finds no tenant, the environment is still imported and saved with an empty TenantId.
• Overwritten environments (see Conflict Resolution) are not probed, and the TenantId from the file is ignored here too: the value stays the one already in the local store, or is invalidated (saved as empty) when the imported EnvironmentUrl really differs from the stored one. Differences of only a trailing slash or of letter case do not count as a change and keep the stored TenantId. The next run of xg env activate <FRIENDLY_NAME> makes a best-effort attempt to recalculate an invalidated TenantId, even if the overwritten environment is already the active one.
• Skipped environments are left unchanged, TenantId included.

---

Conflict Resolution

If an environment with the same FriendlyName already exists in the local store, the command presents an interactive prompt with the following choices:

Choice	Behaviour
Skip	The conflicting environment is left unchanged. The import counter increments skipped.
Overwrite	The existing entry is updated with the imported EnvironmentUrl, AuthenticationMethod, ClientId and MetadataCacheLifecycle, and the client secret is replaced. The TenantId field of the imported file is not read, even when present as in files produced by xg env export: the locally stored TenantId is kept, or invalidated when the EnvironmentUrl really changes (trailing-slash or letter-case differences alone do not count). No tenant probe runs during the import; the next run of xg env activate <FRIENDLY_NAME> makes a best-effort attempt to recalculate it, even if the environment is already active. The import counter increments overwritten.

A third option, Rename, is currently shown in the prompt but is not yet implemented — selecting it results in a skip.

---

Exit Codes

Code	Meaning
0	Command completed (may include skipped entries).
1	Fatal error: file not found, file read failure, or JSON parse error.

---

Examples

Import a single environment from a file

xg env import ./environments/dev.json

Import multiple environments from a bulk export

xg env import ./all_environments.json

Import from an absolute path

xg env import /home/user/configs/xrmghost-envs.json

---

See Also

• xg env template — Generate a blank environment configuration JSON ready to fill in and import.
• xg env list — List all currently registered Dataverse environments.
• CLI Overview — Introduction to the xg CLI, command groups, and how this documentation is organised.