Pages

Import via CLI (Enterprise Edition only)

AppProfileSafe imports can be run from the command line for automation, scripted rollouts, and scheduled restores. The CLI is a separate executable (AppProfileSafe.CLI.exe) that runs the same engine as the GUI with native console support for output redirection and pipes.

Basic Syntax

AppProfileSafe.CLI.exe --import --manifestFile "<path>" --apps "App1,App2,..." [options]

Required Parameters

Parameter	Description
`--import`	Run in import mode
`--manifestFile "<path>"`	Full path to the manifest XML file from a previous export. The directory containing this file is used as the export root.
`--apps "A,B,C"`	Comma-separated list of application names to import (must match `EntryName` values in the manifest). Use `--apps all` to import all applications from the manifest.

Optional Parameters

Parameter	Description
`--mappingFile "<path>"`	Path to a mapping XML file. Registry and file path transformation rules are loaded from this file before import. See Mapping.
`--blackListFile "<path>"`	Path to a BlackList XML file. Items matching blacklist entries are skipped during import. See BlackList Filtering below.
`--noRestorePoint`	Skip system restore point creation entirely. Useful for environments where restore points are not supported or not desired.
`--ignoreRestorePointLimit`	Continue the import even if the system restore point cannot be created (e.g. the Windows 24-hour limit is reached). Without this flag, a failed restore point creation aborts the import.
`--silentMode`	Suppress all console output (log file only)
`--preflight`	Run preflight checks only, without performing the actual import. Produces a JSON report.
`--userSettingsFile "<path>"`	Path to a user settings file that overrides path values from the base `settings.xml`. Only the `<Paths>` block is evaluated. See Configuration: settings.xml.

UNC Network Share Options

When the manifest is on a UNC network share, provide credentials using the same options as for export:

Parameter	Description
`--unc-user "<user>"`	Username for UNC share authentication
`--unc-password "<pass>"`	Password for UNC share authentication
`--unc-credential-store`	Read credentials from Windows Credential Manager

See Working with UNC Paths for details.

BlackList Filtering

The --blackListFile parameter lets you exclude specific items from the import without modifying the backup. This is the CLI equivalent of deselecting items in the GUI's DryRun checkbox view.

The BlackList file is an XML document validated against the AppProfileSafe.BlackList-v1.0.0.xsd schema. It contains one or more <Path> entries, each specifying a destination path to skip. Paths may contain environment variables (e.g. %APPDATA%), which are expanded before matching.

BlackList XML Format

<BlackList xmlns="urn:appprofilesafe:blacklist:v1">
  <!-- Skip this path for all apps and all types -->
  <Path>C:\Users\OldUser\AppData\Local\Temp</Path>

  <!-- Skip only for a specific app -->
  <Path App="Firefox">HKCU\Software\Mozilla\Firefox</Path>

  <!-- Skip only a specific type for a specific app -->
  <Path App="Firefox" Type="File">%APPDATA%\Mozilla\profiles.ini</Path>

  <!-- Skip all RegKey items at this path, regardless of app -->
  <Path Type="RegKey">HKCU\Software\Test</Path>
</BlackList>

Matching Rules

Attribute	Required	Behavior
`Path` (element text)	Yes	Destination path to match. Environment variables are expanded. Registry paths are normalized. Compared case-insensitive against the mapped destination path during import.
`App`	No	If specified, only items belonging to this application are matched. If omitted, the path is matched across all applications.
`Type`	No	If specified, only items of this type are matched. Valid values: `RegKey`, `RegValue`, `File`, `Folder`. If omitted, all types are matched.

All comparisons are case-insensitive. An item is skipped if its destination path, app name, and type all match a blacklist entry (where omitted attributes act as wildcards). Skipped items are reported with the status Skipped (blacklisted).

If the BlackList file is not found, is not valid XML, or fails XSD validation, the import is aborted with exit code 2.

CLI Import Workflow

The CLI import runs through the following steps in order:

Parse arguments — Parse command-line arguments
Help check — If --help is present, print usage and exit with code 0
License validation — Exit code 3 on license failure (checked before parameter validation so the user is informed immediately)
Validate arguments — Exit code 1 on invalid input
Load configuration — Load base settings.xml; if --userSettingsFile is provided, validate against XSD and merge path overrides (exit code 1 on validation failure)
Preflight — If --preflight is specified, run checks and produce JSON report
SIEM test — Exit code 4 if SIEM is active but unreachable
Audit integrity check — Exit code 5 on audit log failure
Single-instance mutex — Exit code 2 if another instance is running
UNC connection — Connect to network share if applicable
System restore point — Created by default; skipped with --noRestorePoint
Load mappings — If --mappingFile is provided, load and validate the mapping rules
Load blacklist — If --blackListFile is provided, load and validate against the BlackList XSD (exit code 2 on failure)
Execute import — Restore registry and files from the backup. Items matching the blacklist are skipped.

System Restore Point Behavior

By default, the CLI creates a system restore point before importing. The restore point description follows the format: "AppProfileSafe Import - Firefox, Chrome... - 2026-02-13 14:30" (first 3 app names, truncated with "..." if more). When --apps all is used, the description shows "All applications".

Scenario	Behavior
Restore point created successfully	Import continues. Duration is logged.
A recent restore point already exists (Windows 24h limit)	Treated as success with a "Skipped" message. Import continues.
Creation fails + `--ignoreRestorePointLimit`	Warning logged. Import continues.
Creation fails + no flag	Import is aborted with exit code 2. Use `--ignoreRestorePointLimit` to continue anyway, or `--noRestorePoint` to skip entirely.
`--noRestorePoint` specified	Restore point creation is skipped entirely. Message: "Restore point creation skipped."

Examples

Basic Import

AppProfileSafe.CLI.exe --import --manifestFile "C:\Backup\Manifest.xml" --apps "Firefox"

Import All Applications from Manifest

AppProfileSafe.CLI.exe --import --manifestFile "C:\Backup\Manifest.xml" --apps all

Import with Mapping File

AppProfileSafe.CLI.exe --import --manifestFile "C:\Backup\Manifest.xml" --apps "Firefox" --mappingFile "C:\Mappings\dev.xml"

Import All with Mapping File

AppProfileSafe.CLI.exe --import --manifestFile "C:\Backup\Manifest.xml" --apps all --mappingFile "C:\Mappings\dev.xml"

Import with BlackList (Skip Specific Items)

AppProfileSafe.CLI.exe --import --manifestFile "C:\Backup\Manifest.xml" --apps "Firefox" --blackListFile "C:\Config\blacklist.xml"

Import with Mapping and BlackList

AppProfileSafe.CLI.exe --import --manifestFile "C:\Backup\Manifest.xml" --apps "Firefox" --mappingFile "C:\Mappings\dev.xml" --blackListFile "C:\Config\blacklist.xml"

Import with Custom User Settings

AppProfileSafe.CLI.exe --import --manifestFile "C:\Backup\Manifest.xml" --apps "Firefox" --userSettingsFile "D:\Configs\test-env.xml"

Import Without Restore Point

AppProfileSafe.CLI.exe --import --manifestFile "C:\Backup\Manifest.xml" --apps "Firefox" --noRestorePoint

Import, Ignore Restore Point Limit

AppProfileSafe.CLI.exe --import --manifestFile "C:\Backup\Manifest.xml" --apps "Firefox" --ignoreRestorePointLimit

Silent Mode

AppProfileSafe.CLI.exe --import --manifestFile "C:\Backup\Manifest.xml" --apps "Firefox" --silentMode

Import from UNC Share

AppProfileSafe.CLI.exe --import --manifestFile "\\server\share\Manifest.xml" --apps "Firefox" --unc-credential-store

Preflight Only (No Actual Import)

AppProfileSafe.CLI.exe --preflight --import --manifestFile "C:\Backup\Manifest.xml" --apps "Firefox" --mappingFile "C:\Mappings\dev.xml"

Exit Codes

Code	Meaning
`0`	Success
`1`	User error — invalid arguments, missing files, or mapping file not found
`2`	System error — import failure, I/O error, failed restore point (without `--ignoreRestorePointLimit`), blacklist validation failure, or insufficient privileges
`3`	License error
`4`	SIEM error
`5`	Audit error

Parameter Validation

The CLI validates parameter combinations and reports clear errors:

--apps all is only valid with --import (export requires explicit application names)
--mappingFile is only valid with --import (rejected in export mode)
--blackListFile is only valid with --import (rejected in export mode)
--noRestorePoint is only valid with --import
--ignoreRestorePointLimit is only valid with --import
--userSettingsFile is valid with all modes (export, import, compliance report, preflight)
If --mappingFile points to a non-existent file, exit code 1 is returned
If the mapping file cannot be loaded (invalid format), exit code 2 is returned
If --blackListFile points to a non-existent file or fails XSD validation, exit code 2 is returned
If --userSettingsFile points to a non-existent file or fails XSD validation, exit code 1 is returned