CLI (erp-preflight)

The CLI is the package @erppreflight/cli (directory packages/cli): a single, dependency-free Node.js script that calls the ERP Preflight REST API. Analyses always run on the server with the deterministic engines; the CLI never evaluates rules locally. It needs Node.js 18 or newer because it uses the built-in fetch.

The package is not published to the public npm registry. From a copy of the package directory, install it globally or run the script directly:

npm install -g ./packages/cli              # provides erp-preflight and erp-preflight-mcp
node packages/cli/bin/erp-preflight.js --help

The CLI authenticates with an organization API key, sent as X-Api-Key.

erp-preflight login --key erppf_live_… --api-url https://api.example.com
erp-preflight status

login checks the key by listing projects (the key needs projects:read) and saves key and URL in ~/.erppreflight/config.json, created with file mode 0600 in a directory with mode 0700. status shows the readiness of the API and whether a key is configured.

• API URL: --api-url, otherwise ERP_PREFLIGHT_API_URL, otherwise the URL saved by login, otherwise http://localhost:3001. /api/v1 is appended when missing.
• API key: ERP_PREFLIGHT_API_KEY, otherwise the key saved by login. In CI, set the environment variable instead of running login.
• Configuration directory: ERP_PREFLIGHT_CONFIG_DIR replaces ~/.erppreflight.

erp-preflight login --key <api_key> [--api-url <url>]
erp-preflight status
erp-preflight project list
erp-preflight project create --name <name> [--release S4H_2023] [--description <text>]
erp-preflight upload <projectId> <file> [file ...]
erp-preflight analyze <projectId> --engines <E1,E2> [--files <id,...>] [--release <release>] [--wait] [--timeout 600] [--fail-on <severities>]
erp-preflight analyze <alias> <path ...> --project <projectId> [--wait] [--timeout 600] [--fail-on <severities>]
erp-preflight findings <projectId> | --analysis <analysisId> [--severity <severity>] [--fail-on <severities>]
erp-preflight report export <projectId> <analysisId> [--format PDF] [--out <file>]
erp-preflight report download <analysisId> [--out <file>]
erp-preflight version

• project create needs the scope projects:write, which keys created in the web app do not have.
• upload sends each file through the server-side upload checks (content type, archive limits, malware scan, secret redaction) and prints its file id, status and number of redactions; with --json also the SHA-256 of the local file. A file that does not end up CLEAN makes the command fail.
• report export generates a report — PDF (default), XLSX, CSV, JSON_BUNDLE or HTML_OFFLINE — saves it under --out or the file name supplied by the server, and prints its SHA-256.
• report download saves the reproducibility bundle of a run as a ZIP file.

To use ERP Preflight tools from a coding agent, see MCP server.

analyze <projectId> starts the engines listed in --engines — engine types such as OPD_GUARD or the aliases below — on the files given in --files, or else on every CLEAN artifact of the project. Without --wait the command returns as soon as the run is queued and prints its id.

With --wait the CLI polls every 2 seconds until the run is COMPLETED, PARTIAL, FAILED or CANCELLED, for at most --timeout seconds (default 600). It then prints the findings — severity, rule, confidence, title and evidence location; the table shows the first 200 — and applies --fail-on (see CI integration).

analyze <alias> <path ...> --project <projectId> uploads local files and runs the matching engine in one step. Aliases: clean-core (CLEAN_CORE_OBJECT_GUARD), api-diff (API_CHANGE_GUARD), mfs (MFS_BLACKBOX), opd (OPD_GUARD), forms (FORM_DOCTOR) and transports (TRANSPORT_DEPENDENCY_ANALYZER). Directories are searched recursively, skipping .git and node_modules, for files ending in .abap, .prog, .incl, .xml, .xsd, .json, .csv, .edmx, .wsdl or .xdp — the analysable types the upload checks accept. Archives, PDFs and text files are uploaded only when you name them explicitly.

findings <projectId> lists the findings of all runs of the project, including earlier detections; findings --analysis <analysisId> lists those of one run. --severity CRITICAL keeps findings of that severity and above.

• --json prints machine-readable JSON instead of tables. For analyze --wait it contains the run id (analysisId), status, engines, number of files, a summary by severity and all findings.
• --http-timeout <seconds> sets the timeout of each HTTP request (default 60).
• Put flags without a value, such as --wait and --json, after the positional arguments: a flag followed by a word that does not start with -- takes that word as its value.

Exit codes:

• 0 — success.
• 1 — error: API or network error, a file rejected or quarantined by the upload checks, no CLEAN artifacts, a run that ended FAILED or CANCELLED, or a --wait timeout.
• 2 — usage or authentication: missing arguments, unknown command, file not found, no API key configured, or HTTP 401/403 from the API (for example a missing scope).
• 3 — quality gate failed (--fail-on).