Monitoring, JSON and Exit Codes

Use --json for every automated call. Diagnostics use structured envelopes and a defined exit-code policy so that scripts and monitoring never have to parse console text.

Result envelope

On success the payload is printed with "ok": true, "exit_code": 0 and "contract": "native-core-0.55" added. On failure a single diagnostic envelope is printed on stdout:

{
  "product": "ChargeLink",
  "cli": "chargelink",
  "contract": "native-core-0.55",
  "ok": false,
  "status": "error",
  "exit_code": 20,
  "command": ["...\\chargelink.exe", "--json", "license", "verify", "--file", "C:/ChargeLinkData/licenses/missing.cllic"],
  "error": {
    "code": "CL-LICENSE-001",
    "category": "licensing",
    "kind": "license",
    "message": "license error: license I/O error: The system cannot find the file specified. (os error 2)",
    "retryable": false,
    "operator_action": "Supply a valid ChargeLink license file or activation package."
  }
}

Without --json, stderr receives [CODE] message (exit_code=N, category=..., action=...). Customer output never contains stack traces. Print the policy with chargelink --json diagnostics exit-codes and chargelink --json diagnostics error-taxonomy; produce a sample envelope for parser tests with chargelink --json diagnostics sample-error --kind runtime.

Exit codes and error codes

Exit	Code	Category	Retryable	Operator action
0	—	success
2	CL-USAGE-001	usage (including clap parse errors)	no	Check command syntax with `--help` and retry.
10	CL-CONFIG-001	configuration	no	Inspect configuration, paths and environment settings.
20	CL-LICENSE-001	licensing	no	Supply a valid license file or activation package.
30	CL-PROFILE-001	profile	no	Validate the selected profile or choose a built-in profile.
40	CL-RUNTIME-001	runtime	yes	Inspect runtime state, run ID, lock files and session lifecycle.
50	CL-ARTIFACT-001	artifact	no	Inspect the artifact root and ensure the run generated artifacts.
60	CL-CONTRACT-001	contract	no	Refresh contract fixtures.
70	CL-UNSUPPORTED-001	unsupported	no	The command is accepted by the parser but has no implementation in the installed version.
80	CL-IO-001	io	yes	Check filesystem permissions, path length and removable or network media.
81	CL-SERIALIZATION-001	serialization	no	Check JSON/YAML syntax and schema compatibility.
90	CL-INTERNAL-001	internal	no	Collect a support bundle and report the defect.

Exit code 70 is also returned when the worker thread cannot start; the message then carries CL-INTERNAL-001. Treat any non-zero exit with retryable: true as transient and everything else as a stop condition in automation.

Runtime health fields

runtime list, runtime inspect, evse status and evcc status return a health object:

Field	Values	Monitor
`status`	`dry_run_validated`, `starting`, `running`, `stop_requested`, `stopped`, `failed`, `recovered_stale`	alert on `failed`
`process_state`	`live`, `not_live_mode`, `missing`	alert when a running session's process is missing
`heartbeat_age_ms`, `stale_after_ms`, `stale`, `stale_reason`	ms; 300000; bool	alert when age approaches the stale limit while running
`active_role_lock`, `session_lock`	`active_role_lock_matches`, `missing`, ...; `present`	lock mismatch indicates a stale or foreign session
`recoverable`, `operator_action`	bool; text	use the text in alerts

gRPC health

HealthService.GetHealth reports SERVING, STARTING, DEGRADED or STOPPING with uptime; WatchHealth streams changes. From the CLI: chargelink --json integration health --endpoint http://127.0.0.1:50051 returns health_status, api_version, product_version and uptime_ms. System signals in the dictionary (System.HealthState, System.CpuUsagePct, System.MemoryBytes, System.DroppedEvents) and Fault.ActiveCount / Fault.LastFault can be polled or subscribed through SignalService.

What to monitor in production

Service health: gRPC serving state; on the VeriStand bench, the owner host's Operator.* status channels and heartbeat.
Session lifecycle: running sessions, heartbeat age, stop requests, stale locks.
Artifact write failures: CL-IO-001 / CL-ARTIFACT-001, free space on the artifact volume, integrity results.
Clock: NTP synchronisation (TLS validity, evidence timestamps).
Safety on plant-coupled benches: Safety.FaultActive, Runtime.CommandAgeActual_ms, Operator.LastErrorCode.
Certificate validity dates of the SECC and vehicle material.
License state (license status) after upgrades and machine changes.

Logging

The CLI writes info-level tracing to stderr; there is no log-level switch or log file option. Redirect stderr in your supervisor if you need a log, and rely on the JSON results and the artifact traces for diagnosis. On the VeriStand bench, every session writes its logs and evidence into its run folder under runs_root.