guara/docs/cli.md

Terminal reference

English · Português

Reading a raw disk requires privileges: administrator on Windows, sudo on Linux and macOS. Use guara <command> --help for the full list of options.

Commands

Command	What it does
devices	Lists disks and USB sticks, warns about TRIM and mounted volumes
inspect <source>	Partitions, unpartitioned space, encryption
health <source>	Disk health (SMART); requires smartmontools
scan <source>	Scan for deleted and lost files
resume <session>	Continues a paused scan
recover <session> <destination>	Recovers the files of a session
image <source> <destination>	Forensic image (raw, E01 or AFF4)
verify <image>	Checks an E01 or Ex01 image against the stored hash
hash <source>	MD5, SHA-1 and SHA-256 of the device
search <source> <terms...>	Text across the whole disk, UTF-8 and UTF-16
export <session> <csv>	Spreadsheet of the findings
report <session> <html>	Printable HTML report
sessions	Automatically saved sessions
ui	Interface in the browser (127.0.0.1, with token)

--json exists on devices, inspect, health and scan.

Scanning

sudo guara scan /dev/sdb --session s.json --list     # deep, with listing
sudo guara scan /dev/sdb --quick                     # metadata only, in seconds
guara scan disk.img --category image,document --min-confidence medium
guara scan disk.img --recover /mnt/other-disk/Recovered

Filters (valid on scan, recover, export and report):

Option	Effect
--category	image, document, video, audio, archive, database, other (comma separated)
--min-confidence	low, medium or high
--name	only names and paths that contain the text
--organize	how to write: folders (original folders), type, date or flat

Recovery

guara recover s.json /mnt/other-disk/Recovered --category image
guara resume s.json

The destination must be on another disk. Every recovery writes guara-manifesto.json with the MD5, SHA-1 and SHA-256 of every file. If the recovery is interrupted, repeating the command skips what was already copied and checked.

Encrypted volumes

sudo guara scan /dev/sdb1 --ask-password
sudo guara scan /dev/sdb1 --recovery-key 111111-222222-333333-444444-555555-666666-777777-888888
sudo guara scan /dev/sdb1 --key-file key.BEK
sudo guara scan /dev/sdb1 --volume-key 4f2a...

Option	Use
--ask-password	Asks in the terminal, without echo. Preferred
GUARA_PASSWORD	Environment variable with the password
--password	Password on the command line (stays in the shell history)
--recovery-key	BitLocker numeric key
--key-file	BitLocker .BEK or LUKS keyfile
--volume-key	Volume key in hexadecimal (the one Guará shows when it opens a volume)
--remember-keys	Stores the keys of opened volumes in the session (never the password)

RAID and LVM

Pass the main disk and the other members with --member, repeated. Use - for a missing disk.

# With mdadm or LVM metadata: Guará reads everything by itself
guara inspect disk1.img --member disk2.img --member disk3.img

# Without metadata: discovers level, stripe size, layout and order
guara scan disk1.img --member disk2.img --member disk3.img --raid

# Fixing what you already know
guara scan disk1.img --member disk2.img --member - --raid \
  --raid-level 5 --raid-chunk-kb 64 --raid-layout left-symmetric --raid-order 0,1,2

Forensic image

sudo guara image /dev/sdb /mnt/other-disk/sdb.img                      # raw, with error map
sudo guara image /dev/sdb /mnt/other-disk/sdb --format e01 \
  --case 2026-001 --examiner "Name" --evidence E1 --description "Laptop HDD"
sudo guara image /dev/sdb /mnt/other-disk/sdb --format aff4
guara verify /mnt/other-disk/sdb.E01

For E01: --segment-mib (size of each segment, default 1500, 0 for a single file) and --compression (0 to 9, default 1).

Video without an index (MP4 without moov)

Pass an intact video from the same camera or drone so Guará can rebuild the index:

guara scan card.img --reference GOOD_VIDEO.MP4 --category video

--reference can be repeated. Audio is not reconstructed.

Text search

sudo guara search /dev/sdb "contract" "ssn" --case-sensitive --max 500

Searches in UTF-8 and UTF-16 (--no-utf16 turns it off), including free space and areas outside partitions. Shows position, partition and context. --max limits the results (default 200).

Report

guara report s.json report.html --case 2026-001 --examiner "Name" --hash-source

Includes case identification, source, partitions, summary, hashes and the list of files. --hash-source adds the hash of the whole source.