SakshyaYantra Forensic Suite on the command line

Folder to write the image into (default: ./Evidence)

When to use it. Point this at the evidence store for the case, not at the machine's own disk. On a booted rescue USB the default writes to the stick itself, which is usually what you want in the field.

What it costs. The folder must have room for the whole source. The pre-flight refuses rather than filling the disk half way through.

Retries for bad sectors (default 3)

When to use it. Raise it when the drive is readable but marginal and the case justifies a slow, thorough pass. Lower it to 0 or 1 when the drive is deteriorating and getting a complete-enough image quickly matters more than the last few sectors.

What it costs. Every retry is another read of a failing surface. On a drive that is physically degrading, high retry counts can cost you the areas you have not reached yet.

Start even if the pre-flight checks object.

When to use it. Only when you have read the pre-flight objection and know it is wrong for your situation, for example free space reported incorrectly by a network share.

What it costs. The pre-flight exists to stop a job that cannot finish. Forcing past a genuine space or same-drive objection loses work, and on the same-drive case it can overwrite the very data being recovered.

Engage a SOFTWARE write-block (OS read-only) on the source first. Best-effort and not a substitute for a hardware write blocker; layered with the fingerprint.

When to use it. Use on every evidential acquisition where no hardware write blocker is available. It sets the operating system's own read-only flag on the source before the first read.

What it costs. It is best effort at the operating-system level and is not equivalent to a hardware write blocker. State which one you used in the report; do not describe a software block as a hardware one.

Image format: raw (.img, resumable) or E01. Asked for when omitted.

When to use it. raw when the image will be recovered from or examined on the same bench and a stopped copy must be resumable (the .map carries on); e01 when it goes to a lab that expects Expert Witness containers or when the destination is smaller than the drive and compression has to make it fit. Asked for on screen when omitted.

What it costs. An E01 copy cannot be resumed part way; a raw copy takes the drive's full size on the destination.

On the RecoverYantra bootable USB: offer the USB's own DATA partition and any other attached drive as the destination, never the drive being copied or the boot medium; record the read-only protection.

When to use it. Set by the RecoverYantra bootable USB's own launcher: the USB's DATA partition is offered first as the destination, then any other attached drive that is neither the source nor the boot medium, and the manifest records that every disk arrived read-only.

What it costs. Outside the bootable USB there is no live medium, so the flag is ignored with a note and -o decides where the image goes.

Examiner asserting lawful authority (recorded)

When to use it. Record the individual asserting lawful authority for the acquisition. Required practice for anything that may be produced in proceedings.

Lawful basis: warrant / consent / statutory power

When to use it. Record the lawful basis: warrant, consent, or a statutory power. Write what it actually is, and keep the underlying document with the case file.

What it costs. This field records the assertion. It is not legal advice and it does not create authority you do not have.

Examiner's organisation (recorded)

When to use it. The examining organisation, as it should appear on the report and in the custody record.

Case / FIR reference (recorded)

When to use it. Your own case or FIR reference. Set it at acquisition so every later artefact carries the same identifier.

What it costs. Adding it afterwards means the earliest records in the trail carry a different reference from the rest.

Path to audit_trail.jsonl (or the folder holding it)

When to use it. Run at the close of a case, and again before disclosure, against the audit_trail.jsonl produced during the work. It proves the trail has not been edited, reordered or had entries inserted.

A recovery_manifest.json holding the sealed receipt, so entries REMOVED from the trail are detected too

When to use it. Add the recovery manifest whenever you need to prove nothing was REMOVED from the end of the trail. The manifest holds the sealed receipt the chain alone cannot see past.

What it costs. Without it, a trail that has been cut short at the end still verifies. For evidential work treat the manifest as required.

When to use it. Queue several drives to image and/or recover, then run them in sequence with nobody watching. `new` starts a batch; `add` queues a job on it; `list`/`status` show its progress; `remove`/`move` edit the queue before it runs; `start`/`resume` run it; `pause`/`stop` are typed in another window while it is running; `report` writes what happened across the whole batch. Use it when there are more drives on the bench than there is time to sit and watch each one.

When to use it. Group several recovered sources - a laptop disk, a backup stick, a phone image - into one case for a single customer or job, and see everything recovered across them in one place, deduplicated by hash. `new` starts a case; `add` puts a source into it; `list` shows the cases or one case's sources; `status` totals its files and duplicates; `dedup` lists files found in more than one source. Use it when a job is more than one drive and you do not want to hand back the same file three times.

Recorder disk (e.g. \\.\PhysicalDrive2 or /dev/sdb)

When to use it. Point at the recorder's disk when you have the disk itself and the recorder is unavailable or its export function is broken.

What it costs. Reading a recorder disk directly is read-only, but the recorder must be powered down and the disk removed. A running recorder overwrites the oldest footage continuously.

Image of the recorder disk (.dd/.img/.e01)

When to use it. Preferred over --device for any matter that may be produced. Image the recorder disk once, then work from the image.

Where to write recovered clips (required when scanning a disk/image)

When to use it. A folder on the case store with room for the clips. Recorder disks are large and footage recovers as many separate files.

Ignore fragments smaller than this many bytes (default 65536)

When to use it. Raise it when a sweep is returning large numbers of very short fragments and the incident you care about is minutes long. Lower it when the event of interest is only a few seconds.

What it costs. Raising the floor discards short fragments permanently for that run. If the incident may be brief, run low first and filter afterwards.

Stop after N clips

When to use it. Cap the run when you are sampling a large recorder to establish what is on it before committing to a full extraction.

What it costs. A capped run is not a complete extraction. Say so in the notes, and do not report the cap as the total footage present.

Just report which recorder this disk is, don't extract

When to use it. Run first on any unfamiliar recorder disk. It reports which recorder wrote the disk without extracting anything, which tells you how long the real job will take and whether the format is supported.

Start even when the pre-flight checks say this cannot finish: too little room, or writing onto the drive being recovered.

When to use it. Only after reading the objection. See the same switch on acquire.

What it costs. Forcing past a same-drive objection can overwrite the footage you are extracting.

When to use it. Read the recorder's camera index, play a clip's timeline, list a scan's clips, download or cut one out, extract several, enhance a frame or a range, capture a frame pack, or build a media report. Every subcommand is documented on its own line.

Raw device path (e.g. \\.\PhysicalDrive1 or /dev/sdb)

When to use it. Run the feasibility check the moment a drive arrives, before quoting, before imaging and before any promise to the client: it measures how much of the drive is unreadable and states the chances in plain words.

What it costs. A few hundred sampled reads - seconds on a healthy drive, and one gentle attempt per area on a failing one. Far cheaper than discovering mid-copy that the job was never viable.

An existing image file to check instead

When to use it. Check an existing image instead of a drive - for example to confirm a copy received from a client or another lab reads cleanly before work is billed against it.

Also write the answer as a PDF report at this path

When to use it. Write the verdict as a PDF wherever a client, insurer or case file needs the answer on record. The report states its numbers as ranges and says it is based on a sample.

How many areas of the drive to test (default 160)

When to use it. More samples narrow the stated range and cost more reads of the drive. The default suits a first assessment; raise it when the estimate must be tighter than a few percent.

What it costs. Each extra sample is another read of a drive that may be dying. On clearly failing hardware, keep the default and move to the copy.

Scan A: a session id from the history, or a recovery output folder

When to use it. The FIRST scan - a session id from the history, or the path to a recovery output folder. Normally the earlier pass, so that what the second scan added reads as the gain.

Scan B: the re-scan / deeper scan, same kind of reference

When to use it. The SECOND scan of the same source - the re-scan, the deeper scan, or the one run after a settings change. Files only in this scan are what it added, which is usually the reason for comparing at all.

What it costs. Comparing is read-only and charges nothing: it reads what the two scans already wrote. Files are matched by EXACT SHA-256 - a file with the same NAME but different bytes is reported in its own bucket and is never called the same file, because a deleted name can survive while the space under it is reused.

Write the diff to this folder (scan_compare.csv/.json)

When to use it. Write the comparison into this folder - scan_compare.csv or .json - so the four buckets go into a job sheet or a report rather than staying on screen. The folder is created if it is not there.

Export format (default csv)

When to use it. csv (the default) writes one row per file occurrence, so a changed file appears twice with its A side and its B side and the sheet opens in Excel; json writes the whole comparison for a script.

Identify a database file and print its recovery method

When to use it. Run this first on any database file. It names the engine and the recovery method that applies, which decides whether this is a ten-minute job or a specialist one.

List every database family we cover and the recovery tier

When to use it. Use when quoting or scoping. It lists every database family the build covers and the tier of recovery available for each.

What it costs. A family listed at identify-and-route tier is not row-level recovery. Quote against the tier, not the presence in the list.

Recover records from a database file (dBase/.dbf built; others are identified and routed to their method)

When to use it. Point at a copy of the data file when the server will not start or will not attach it, and the most recent backup is unusable.

What it costs. Work from a COPY. Take the instance offline first: extracting from files a running engine is writing to produces rows from a moment that never existed as a consistent state.

With --recover of a .dbf: the memo side-file (.dbt/.fpt)

When to use it. Required with a dBASE .dbf whose text fields live in a side file. Without it the long text fields come back empty.

With --recover: write all records (deleted marked) to a CSV

When to use it. Write to CSV whenever the rows are going to be reviewed, handed to a client, or loaded into a working server.

What it costs. Deleted rows are exported flagged. Preserve that column: an un-flagged export presents recovered deleted rows as live data.

When to use it. Pick what to do: `plan` shows how the work would split and what it refuses without needing nodes; `node` runs a worker that searches byte ranges; `carve` coordinates a distributed carve and writes the files here.

A filename, part of one, or a wildcard (e.g. IMG_2019, *.jpg)

When to use it. Search every usable attached device for a file whose name matches PATTERN, without picking a drive first. Free, no licence needed - reads each device's index in seconds, the same tier as `--list`. Use it when the customer cannot say which of several drives holds what they want.

Give up on one drive after this long (default 20); a slow or failing drive never holds up the others

When to use it. Seconds allowed per device before moving on. A slow or failing device costs only its own row - the sweep never waits on one device at the expense of the rest.

List every drive checked, including the ones with no match

When to use it. Also sweep devices that are not in a normally-usable state, where possible. Use it only once the plain sweep has come back empty.

When to use it. Bring footage in, decode it, batch-convert it, check the tested-recorder registry, or see what this machine's media worker can handle. Every subcommand is documented on its own line.

When to use it. Map the case's location points. `points` prints them (and the track) as JSON; `export` writes GeoJSON (RFC 7946) or KML (opens in Google Earth / QGIS). Only files carrying real EXIF GPS appear - nothing is guessed from a name.

Write the guide as a self-contained, searchable HTML page

When to use it. Produce the manual as a single searchable page to hand to a client, put on an internal share, or carry onto an air-gapped bench.

Write the guide as Markdown

When to use it. Produce Markdown when the content is going into your own documentation system or version control.

The physical drive (e.g. \\.\PhysicalDrive2). Must be a direct SATA connection - USB bridges do not pass ATA

When to use it. The physical drive to measure or reveal, as a device path. It must be a DIRECT SATA connection: USB bridges and virtual disks do not pass the ATA commands a Host Protected Area is measured with.

Actually lift the HPA and image the hidden sectors (needs -o and --confirm-serial); without it, only measure

When to use it. Actually lift the Host Protected Area and image what it hid, instead of only measuring. This is one of the four operations in the whole product that WRITE to a drive, so it is deliberate and confirmed.

What it costs. It sends a volatile SET MAX ADDRESS to the drive to expose the hidden sectors, images them, then restores the original limit - and restores it even if the run is interrupted. The drive is briefly changed on purpose; a DCO, if present, is measured but never removed.

Where to write the image of the hidden area (with --reveal)

When to use it. Where to write the image of the revealed hidden area. Choose a folder on another drive; the hidden sectors, their map and a hashed manifest are written there.

Type the drive's own serial number back to confirm the target (with --reveal)

When to use it. Type the target drive's own serial number back, exactly, to confirm you mean this drive before anything is written to it. The reveal is refused until it matches.

What it costs. This is the guard against revealing the wrong drive: a write to a drive's ATA limits is not something to do to the wrong one, so the serial must match what the drive reports.

Recorded in the audit trail (with --reveal)

When to use it. A name recorded in the audit trail for the reveal, so the record says who performed it. It is written into the manifest, not onto the drive.

Write the image even if the pre-flight objects

When to use it. Write the image of the hidden area even when the pre-flight objects, for example over tight free space at the destination. Use it only after reading the warning.

What it costs. The pre-flight is what stops a half-written image of the hidden area; forcing past it can leave the imaging incomplete even though the HPA is still correctly restored.

When to use it. Add evidence to a case and process it through one pipeline with a live dashboard. `add` enqueues a source; `run` runs the stages; `status` prints the dashboard; `stop` halts at a stage boundary; `retry` re-queues a failed stage.

Show what has been acknowledged on this install

When to use it. Show what lawful-use acknowledgements have been made on this install. Useful when auditing a shared bench machine.

Forget remembered acknowledgements (history is kept)

When to use it. Clear the remembered acknowledgements when a machine changes hands or a new operator takes it over.

What it costs. The history is retained. Resetting does not erase the record of what was previously acknowledged.

Also check each device's health (SMART + test reads), how it's connected, and what kind of device it is (CCTV recorder, phone, dashcam, card, ...) with advice on what to do

When to use it. Run before touching anything. It reports each device's health, how it is connected and what kind of device it is, which is what decides whether to recover directly or image first.

What it costs. Triage reads the drive. On a drive that is audibly failing, keep even this brief and go straight to imaging.

When to use it. Run a saved recipe, save or list one, or take a calibrated 2-D measurement. The Lab is in the SakshyaYantra Forensic Suite; the separate Forensic Video Lab product left the catalogue on 2026-09-16 and its work is in the Forensic Suite.

Switch mode; omit to just show the current mode

When to use it. Set forensic before an evidential job and recovery before a commercial one. Forensic hashes every item, writes the chain-of-custody manifest and keeps a flat layout; recovery skips per-file hashing, sorts the output by type and repairs damaged files on export.

What it costs. The mode changes real engine behaviour, not only the wording of the report. Set it BEFORE the scan: a recovery-mode scan does not become evidential retrospectively.

A frame-pack .zip

When to use it. A frame-pack .zip - the only unit this door accepts. A video, a clip or a loose picture is refused by type.

Finding ids to submit (default: every frame in the pack)

When to use it. Which finding ids in the pack to submit; defaults to every frame in it.

What it costs. Every frame submitted leaves the machine if the request proceeds - the transfer manifest records each one's digest.

When to use it. The AI provider to ask, once the examiner's own reading is already sealed.

When to use it. The model to ask, from that provider's list.

When to use it. The case this submission is recorded against.

The examiner's own sealed reading, typed BEFORE any model answer is shown; omit to stop at the seal step

When to use it. The examiner's OWN reading, typed and sealed before any model answer can be shown.

What it costs. Omit it (and --unreadable) and the command stops at the seal step - there is no route to an answer without a sealed reading first.

Examiner's name, recorded on the sealed reading (not in the grammar table; added because seal_reading requires one - documented in PARAM_GUIDANCE)

When to use it. The examiner's name, recorded on the sealed reading.

The examiner's reading is that the plate cannot be read (not in the grammar table; the alternative to --reading text - documented in PARAM_GUIDANCE)

When to use it. The examiner's reading is that the plate cannot be read - the alternative to typing --reading text; still a sealed reading, not a bypass of one.

cloud = ask a VLM provider; local = the on-machine YuNet+fast-plate-ocr plate model, no internet; openalpr = the OpenALPR engine (AGPL-3.0), also on-machine and offline (documented in PARAM_GUIDANCE)

When to use it. cloud asks a VLM provider (the frame pack leaves the machine); local reads with the on-machine YuNet+fast-plate-ocr model, no internet and nothing sent; openalpr reads with the OpenALPR engine (AGPL-3.0), also on-machine and offline.

What it costs. local and openalpr both spend nothing and send nothing; local uses the bundled/signed plate model, openalpr needs OpenALPR installed (Python binding or the `alpr` command). With neither the chosen engine refuses honestly rather than guessing; the examiner's sealed reading is still the record and rides ahead of any engine read.

Country whose plate syntax the read is checked against (IN built; documented in PARAM_GUIDANCE)

When to use it. The country whose plate syntax the read is checked against. India is built to full depth; another country is reported as observed and not forced into a format it has no pack for.

Plate format family to validate under: hsrp, bh, special, none (documented in PARAM_GUIDANCE)

When to use it. The plate format family to validate the read under - hsrp, bh, special, or none. Empty uses the country's default (HSRP for India).

Raw device path (e.g. \\.\PhysicalDrive1 or /dev/sdb)

When to use it. Recover directly from the attached drive when it is healthy, the job is not evidential, and time matters.

What it costs. If the drive is failing, image it first. A direct scan reads the whole surface and can be the read that finishes a dying drive.

Disk image file (.dd/.img/.iso)

When to use it. The default choice for anything evidential, anything failing, and anything where the original must be returned untouched.

An iOS (iTunes/Finder) backup folder (Manifest.db)

When to use it. Point at an iTunes or Finder backup folder when the handset itself is unavailable, locked, or must not be touched.

Storage Spaces slab-map JSON: reassemble a pool virtual disk from member images and recover from it

When to use it. Reassemble a Storage Spaces virtual disk from member images and recover from the assembled volume.

Output directory for recovered files (required unless --list)

When to use it. Always a separate drive from the source. The product refuses a destination on the drive being read.

smart=metadata+carving (default), fs=named files only, carve=signatures only

When to use it. Leave at smart. It parses the file system for original names and folders AND carves free space for what the metadata no longer covers. Use fs when you want named files quickly from an intact file system; use carve on formatted or badly damaged media where the metadata is gone.

What it costs. fs alone misses everything the file system no longer indexes. carve alone returns files without their original names or folders. smart is what maximises the result.

Carry on from where an earlier scan of the same source into the same output folder stopped, instead of starting again from the beginning

When to use it. Continue a scan that was stopped, on the same source into the same output folder. A large drive is an overnight job and does not need to be restarted.

What it costs. The checkpoint belongs to the DRIVE, not the path. A different disk in the same slot restarts from the beginning, with the reason stated.

Also recover currently-existing (non-deleted) files

When to use it. Add whenever the loss is a volume rather than a deletion: a reformatted disk, a RAW volume, a failed array. In those cases the files were never deleted and the default deleted-only view will look almost empty.

What it costs. It substantially increases the output size, because it recovers everything present as well as everything deleted.

Print the drive's folder tree from its index (live and deleted files) and stop. Fast; nothing is written. -o is not needed.

When to use it. Look before you scan. Reads the filesystem index only and prints the folder tree - live and deleted files, deleted ones marked - in seconds, writing nothing. Use it first on any drive whose index is intact: it tells you whether the folder the customer wants is still named, so you can recover that alone with --only instead of reading the whole drive.

What it costs. Free, and needs no licence. What it cannot show is anything whose index entry is gone - a formatted card, a wiped table - which still needs the full scan.

Recover only this folder or file (repeatable). Paths are the volume's own, e.g. --only /Users/jo/Documents/ --only /Photos/IMG_0042.jpg. Implies --mode fs and --include-intact.

When to use it. Recover one folder or file rather than everything: the customer wants the Documents folder, not four hours and a terabyte of working folder. Repeat the switch for several paths; a folder path takes everything under it, and 1:/Folder/ names the folder on partition 1 only. Paths are the volume's own, as --list prints them.

What it costs. Implies --mode fs and --include-intact. Every content check, the manifest and the organising run exactly as in a full scan; a use is still charged for the drive.

native=built-in (default), photorec=use TestDisk's PhotoRec, auto=PhotoRec if installed

When to use it. Leave at native. Select photorec only to cross-check a result with a second implementation, which is occasionally useful in a disputed matter.

What it costs. The external engine must be installed separately and does not carry this product's validation or its verdicts.

Carving processes: 0=auto/all cores (default, byte-identical output, ~3x faster), 1=single-threaded, N=that many

When to use it. Leave at 0 so the carve uses the available cores. Set 1 when you need the machine responsive for other work, or when reproducing a result exactly for a report.

What it costs. Output is byte-identical either way; only the time changes. Below about 128 MB the product stays single-threaded because process start-up costs more than it saves.

Bytes per sector (default 512)

When to use it. Change from 512 only for 4K-native drives, where the wrong value prevents the volume being recognised.

Unlock an encrypted drive. A BitLocker 48-digit recovery password, a LUKS passphrase, or a key in hexadecimal.

When to use it. Supply the BitLocker recovery password, LUKS passphrase or hex key for an encrypted volume.

What it costs. Without the correct credential the volume cannot be read by anyone. The product states that rather than returning fragments. The credential is not retained for a later resume.

Start even when the pre-flight checks say this cannot finish: too little room, or writing onto the drive being recovered.

When to use it. Only when you have read the pre-flight objection and established that it is wrong for your situation.

What it costs. The two objections it can override are both serious: too little room means the scan stops part way, and writing onto the drive being recovered overwrites the data you are trying to get back.

Generate a recovery report after scanning (comma-separated: pdf,docx,html; default all)

When to use it. Generate the report at the end of the scan whenever the result goes to somebody else: a client, an insurer, or a case file.

Override the mode for this run (forensic=hash+manifest+evidence, recovery=fast+by-type). Defaults to the saved global mode.

When to use it. Override the saved mode for this one run, for example a single evidential job on a bench normally used for commercial recovery.

What it costs. Setting it per run avoids the more common error, which is leaving a bench in forensic mode and hashing every file on high-volume commercial work.

List the APFS snapshots on the source (point-in-time views that may hold deleted/overwritten files) and stop

When to use it. Run first on any Mac volume. Snapshots are point-in-time views that often still hold the file as it was before it was deleted or overwritten.

Recover files as they were in this named APFS snapshot (byte-exact from the copy-on-write extents)

When to use it. Recover from the named snapshot. Where the file exists in a snapshot, this returns it byte-exact and is far better than carving for it.

List the Windows Volume Shadow Copies on the source (previous versions - originals from before deletion or ransomware) and stop

When to use it. Run first on any Windows volume, and always in a ransomware incident. Shadow copies hold previous versions from before the deletion or the encryption.

Recover files as they were in this shadow copy: the snapshot-time volume is reconstructed and scanned

When to use it. Reconstruct the volume as it was at that snapshot and recover from it. This is frequently the fastest complete recovery available.

When to use it. Work with a machine across the network. `agent` runs on the far machine and offers its disks read-only; `discover` and `list` find it and show what it has; `image` copies a disk that is not in use; `volumes` asks a running machine what it has and whether it can be frozen; `live` acquires a machine that is STILL IN USE, through a snapshot taken on that machine. Use the network route when the drive cannot be removed: a machine under warranty, a server that cannot be opened, a member of staff three time zones away, or a site you cannot attend.

What it costs. The transfer is only as reliable as the link. The image is verified on arrival, and a short image is reported failed rather than handed over as complete. `live` additionally creates a snapshot on the far machine, which allocates space there - so a live acquisition writes to the endpoint even though it never writes to the data being acquired, and every result records that. A volume that cannot be frozen is refused rather than read while it moves. Live acquisition is built into Enterprise, Forensics and the Suite.

When to use it. Open an asset's timeline, build a frame pack from a range, bookmark one frame, read the gaps and field order, or verify a pack already built. Documented per subcommand.

The image or file to analyse

When to use it. The image or file to examine for hidden data, run whenever an exhibit might carry a concealed payload - a picture that is larger than its content explains, a file a suspect treated as important, or anything flagged for a second look. Reading only; the exhibit is never changed.

Also carve out and save any hidden data that is found

When to use it. Add this when the examination should also carve out and save what it finds, so recovered appended data, embedded files and LSB payloads land in a folder you can open, not only in the on-screen verdict.

What it costs. It writes new files to the output folder; it never alters the exhibit, and an unconfirmed carve is labelled so it is not mistaken for proven.

Folder to write recovered hidden data into (with --extract)

When to use it. Where the recovered hidden data is written when extraction is on, used when the default folder beside the exhibit is not where the case keeps its working files. Choose a case folder, never the exhibit's own media.

Print the full report as JSON instead of as text

When to use it. Print the full report as JSON instead of text, used when another tool or a case script consumes the result rather than a person reading it.

Artefact files or a folder to walk

When to use it. Point at the artefact files or the folder holding them. Use when the question is the sequence of events rather than the content of a file.

Write the timeline to this file (else a summary is printed)

When to use it. Write to CSV whenever the timeline is going into a report or a review platform.

Export format for --out: csv (l2tcsv-compatible, the log2timeline/Timesketch CSV) or json

When to use it. Choose the export format for --out: csv writes an l2tcsv file (the log2timeline/Timesketch CSV every timeline tool reads), json writes a machine-readable sibling.

Only events on/after this time (ISO)

When to use it. Bound the timeline to the period in question. On a busy machine the unbounded timeline is too large to read.

Only events on/before this time (ISO)

When to use it. The other bound. Set both when the incident window is known.

Only this artefact kind (substring)

When to use it. Narrow to one artefact type when testing a specific hypothesis, for example execution evidence only.

What it costs. Narrowing hides context. Establish the sequence on the full timeline before filtering it for the report.

Only rows from this evidence source (substring)

When to use it. Narrow to one evidence source (an artefact file or, in a case, an exhibit) when you already know which object the question is about.

Only rows whose text matches (substring)

When to use it. Filter to rows mentioning a filename, a user or a device.

Cap the number of rows

When to use it. Cap the number of rows while you are still working out which period and which artefacts matter.

What it costs. A capped timeline is a sample, not the record. Remove the cap before the run that produces the report.

Skip this many rows first (paging, with --limit)

When to use it. Page deeper into a large timeline together with --limit; the first --offset rows are skipped.

Instead of rows, print the event count per time bucket (the data behind the zoomable view)

When to use it. Print the event count per time bucket (year/month/day/hour/minute) instead of rows - the shape of activity that tells you which window to zoom into before you read individual events.

Print the listing (or histogram) as JSON to stdout

When to use it. Emit the listing (or the histogram) as JSON for a report generator or another tool, rather than the human summary.

Also fold in an existing log2timeline/psort l2tcsv export before filtering

When to use it. Fold an existing log2timeline/psort l2tcsv export in beside the native events, so a full plaso run and our artefact parsers share one timeline.

Which groups to run (DFR CARV WB AUD IMG SS); default all

When to use it. Run the shipping engine against known ground truth. Do this on a new bench, after an upgrade, and on a schedule your quality process sets.

What it costs. This is modelled on the NIST CFTT specifications. It is not a NIST certification and the report says so; describe it accurately.

Folder to write validation_report_<time>.json/.txt into

When to use it. Write the dated validation report to the quality records store.

Also print/write a NIST-Federated-Testing-styled conformance report (test cases grouped by FT tool category; modelled on CFTT FT, not NIST-issued)

When to use it. Add the Federated-Testing-styled conformance report when your accreditation or client requires test cases grouped by tool category.

When to use it. Open an artefact in a structured viewer without leaving the case: `registry` browses a hive, `plist` shows a property list, `sqlite` browses a database and its deleted rows, `hex` pages raw bytes, `interpret` decodes the bytes at an offset, `bookmark` marks bytes on the case. Every view prints JSON.

Workflow id (e.g. data_recovery); omit to list them

When to use it. Print the guided steps for a workflow. Useful for a new operator, or for a procedure your team runs rarely enough to want the sequence in front of them.

List the available guided workflows

When to use it. List the guided workflows available in this product.