Collect diagnostics explicitly
Applies to CLI 0.17.5 and the retained 0.16.0 diagnostic helpers.
See releases. Windows snapshots use schema 1.0; Linux
snapshots use schema 2.0.
Forge Diagnostics is a one-shot collector, not a monitor or repair engine. The Daemon does not schedule collection. Select the smallest set of sections that can answer the current question.
Collect from one target
forge diagnostics collect --device <device-id> --sections identity,storage --output snapshot.json
For a connected Rescue session:
forge diagnostics collect --rescue-code <session-code> --profile reliability --output rescue-snapshot.json
Rules:
- Supply exactly one of
--deviceand--rescue-code. - Supply exactly one of
--sectionsand--profile. - Always supply
--output, a private local file path on the technician workstation. - Use comma-separated section names. Unsupported platform selections fail before helper upload.
- Choose a new output filename for each collection. Linux refuses to overwrite an existing snapshot; Windows can replace it.
Collection verifies the helper, uploads it over the authorized connection, checks the remote hash, runs the selected sections, downloads and hash-checks the JSON, then attempts remote helper/output cleanup.
Available sections
| Section | Windows x64 | Linux x64 |
|---|---|---|
identity |
Yes | Yes |
hardware |
Yes | Yes |
storage |
Yes | Yes |
network |
Yes | Yes |
runtime |
Yes | Yes |
reliability |
Yes | Yes |
drivers |
Yes | No |
events |
Yes | No |
security |
Yes; JSON field windows_security |
No |
Profiles expand to fixed selections, not background monitoring:
| Profile | Windows sections | Linux sections |
|---|---|---|
quick |
identity, hardware, storage, drivers, network, runtime, security | identity, hardware, storage, network, runtime |
reliability |
identity, storage, drivers, events, reliability | identity, storage, runtime, reliability |
security |
identity, network, security | Unavailable |
full |
All Windows sections | All Linux sections |
full is explicit permission to collect every implemented section; prefer
narrower selections for routine investigation.
Understand the result
The CLI receipt includes the target, output path, snapshot schema,
requested_sections, completed_sections, failed_sections, warning count,
helper/transfer hashes and remote_cleanup_succeeded. Optional session_id
correlates the operation with Access History.
The snapshot contains its own schema_version, collector_version,
collected_at_utc, requested sections and structured warnings. Successful
sections survive partial collector failures. Read the warnings and each
section's availability before interpreting missing data as a healthy result.
If the receipt reports cleanup_required, the downloaded snapshot may still
be usable, but remote cleanup is unconfirmed. Use the reported cleanup path
and authorized access to remove only that operation's temporary directory.
Do not turn an unknown cleanup outcome into a success claim.
Linux adds platform and collection_scope: "running-os". It collects the
running OS—including a live USB OS—not an offline installation. It requires
normal native facilities such as procfs, util-linux, iproute2 and systemd
tools. Missing tools or journal access generate warnings; the collector does
not install prerequisites. Linux collection has no SMART, Windows security,
driver inventory, raw journal messages, process command lines or environment
collection.
Windows SMART is a separate explicit request
Ordinary storage collection is not a SMART self-test. Windows SMART
collection requires all of:
--smart-device <device-selector>;--smartctl-uri <verified-https-artifact-url>;--smartctl-sha256 <expected-digest>;--smartctl-publisher "<exact-certificate-subject>".
Only add --smart-short-test when a short self-test is specifically
authorized. Obtain artifact identity through a trusted software source; do
not invent a digest or bypass publisher checks. Linux rejects these options.
Handle evidence privately
Snapshots can contain device identity, hardware, network and operating-system information. Collection is not anonymization. Review scope and sensitivity before sharing through an approved support channel.
Bridge Access History records operation metadata, not snapshot contents. Keep observations and interpretations separate in case notes, and include only necessary evidence. Diagnostics do not themselves approve repairs or prove that a repair succeeded.