Skip to content

Files

The dorsal file command group covers operations on a single file.

This is where you'll extract metadata, generate hashes, create reports, and push a file's metadata to DorsalHub.

This guide covers the five sub-commands:

  1. scan: View all extracted metadata in your terminal.
  2. hash: Get just the content hashes for a file.
  3. report: Generate an HTML report.
  4. identify: Get metadata about a file from DorsalHub.
  5. push: Upload a file's metadata to DorsalHub.

dorsal file scan

This is your primary command for local file inspection. It displays metadata for a single file in the terminal.

Example

  1. Find a file on your system (like a PDF or image) and copy its path.

  2. Run dorsal file scan with the path to your file, like so:

    dorsal file scan /path/to/your/file.pdf

The metadata extraction process may take a few seconds, depending on the size of the file.

When it's complete you'll see a panel, which includes basic file info, hashes, and any file-type specific metadata that the annotation models could infer:

📄 Scanning metadata for PDFSPEC.pdf
╭───────────────────────────────── File Record: PDFSPEC.pdf ─────────────────────────────────╮
│                                                                                            │
│    Hashes                                                                                  │
│       SHA-256:  3383fb2ab568ca7019834d438f9a14b9d2ccaa2f37f319373848350005779368           │
│        BLAKE3:  9abdfb32750a278d5ca550b876e94a72cd8eec82d0e506a127dfb94bd56ca4b2           │
│          TLSH:  T13465D67BB4C61D6DF893CA46571C579B8B0D71533BAEA58604BDAF0AC6338029AC3F41   │
│                                                                                            │
│    File Info                                                                               │
│     Full Path:  /dev/test/docs/PDFSPEC.pdf                                                 │
│      Modified:  2025-04-09 15:09:05                                                        │
│          Name:  PDFSPEC.pdf                                                                │
│          Size:  1 MiB                                                                      │
│    Media Type:  application/pdf                                                            │
│                                                                                            │
│    Tags                                                                                    │
│        No tags found.                                                                      │
│                                                                                            │
│    Pdf Info                                                                                │
│            author:  Tim Bienz, Richard Cohn, James R. Meehan                               │
│             title:  Portable Document Format Reference Manual (v 1.2)                      │
│           creator:  FrameMaker 5.1.1                                                       │
│          producer:  Acrobat Distiller 3.0 for Power Macintosh                              │
│           subject:  Description of the PDF file format                                     │
│          keywords:  Acrobat PDF                                                            │
│           version:  1.2                                                                    │
│        page_count:  394                                                                    │
│     creation_date:  1996-11-12T03:08:43                                                    │
│     modified_date:  1996-11-12T07:58:15                                                    │
│                                                                                            │
│                                                                                            │
╰────────────────────────────────────────────────────────────────────────────────────────────╯

Large files take longer to scan

  • dorsal file scan calculates cryptographic hashes immediately. This process reads every byte of the file and is bound by your disk read speed.

  • Subsequent scans of the same file will be instant because of to the Local Record Cache.

Note: If you are running Dorsal in WSL2 in Windows, please read: WSL2 Performance.

Options

  • Output a machine-readable JSON to the terminal with --json

    dorsal file scan /path/to/your/file.pdf --json

  • Save a JSON output to the default directory with -s or --save:

    dorsal file scan /path/to/your/file.pdf -s

  • Save an HTML report to the default directory with --report:

    dorsal file scan /path/to/your/file.pdf --report

  • When saving a report, use a specific report template with --template or -t:

    dorsal file scan /path/to/data.bin --report --template "default"

  • Choose where the JSON or HTML report are saved with -o or --output:

    dorsal file scan /path/to/your/file.pdf --report -o "my cool report.html"

  • Run the command using the local cache (default)

    dorsal file scan /path/to/your/file.pdf --use-cache

  • Run the command without using the local cache

    dorsal file scan /path/to/your/file.pdf --skip-cache

  • Run the command, forcing an overwrite of the local cache

    dorsal file scan /path/to/your/file.pdf --overwrite-cache

CLI Docs

 Usage: dorsal file scan [OPTIONS] PATH                                       

 Scans and displays the full metadata for a file, with options to save reports. 

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * path      FILE  The path to the file to scan. [required]                  │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                 │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Cache Options ─────────────────────────────────────────────────────────────╮
│ --use-cache           Force the use of the cache, overriding any global     │
│                       settings.                                             │
│ --skip-cache          Bypass the local cache and re-process the file.       │
│ --overwrite-cache     Re-process file and overwrite the local cache entry.  │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Output Options ────────────────────────────────────────────────────────────╮
│ --json                  Output JSON to stdout. Can be combined with --save. │
│ --save    -s            Save a JSON report to the default directory or      │
│                         --output path.                                      │
│ --report                Generate a self-contained HTML report to the        │
│                         default directory or --output path.                 │
│ --output  -o      PATH  Custom output path (file or directory) for          │
│                         generated reports.                                  │
│ --template -t     TEXT  Name or path of the report template to use.         │
│                         [default: default]                                  │
╰─────────────────────────────────────────────────────────────────────────────╯

dorsal file hash

This command generates one or more hashes for a specific file.

Example

  1. Find a file on your system and copy its path.

  2. Run dorsal file hash with the path to your file, like so:

    dorsal file hash /path/to/your/file.pdf

When it's complete, you'll see a panel with the calculated hashes:

╭───────────────────────────  Hashes for file.pdf ───────────────────────────────────╮
│ SHA-256:  dc2146a2b1172def56730143ad80cd1825b7fad15f1fc9c23a4e7d01a741ac11         │
│  BLAKE3:  6e2705bec1ae55bbf3ddd0d44305bf83fa847339bb32f05494a307b7ff223ac4         │
│    TLSH:  T1AE7933F5A7329607815E36F8EB025F12DC44FC931E3E976A339B12B91E853256C63B18 │
│   QUICK:  9810dd75bba04f061f0ea52021930edd2d24fc895850b8eeeb659d17e13b64a6         │
╰────────────────────────────────────────────────────────────────────────────────────╯

Options

  • Get a specific hash by passing either --sha256, --tlsh, --quick or --blake3:

    dorsal file hash /path/to/your/file.pdf --sha256

  • Combine multiple hashes:

    dorsal file hash /path/to/your/file.pdf --tlsh --quick

  • Get the result as a JSON with --json:

    dorsal file hash /path/to/your/file.pdf --json

  • Run the command using the local cache (default)

    dorsal file hash /path/to/your/file.pdf --use-cache

  • Run the command without using the local cache

    dorsal file hash /path/to/your/file.pdf --skip-cache

CLI Docs

 Usage: dorsal file hash [OPTIONS] PATH                                       

 Calculates and displays cryptographic and specialized hashes for a single    
 file.                                                                        

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * path      FILE  The path to the single file to hash. [required]           │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --sha256        Display the SHA-256 hash.                                   │
│ --blake3        Display the BLAKE3 hash.                                    │
│ --tlsh          Display the TLSH similarity hash.                           │
│ --quick         Display the sample-based QuickHash.                         │
│ --json          Output hashes as a raw JSON object.                         │
│ --help          Show this message and exit.                                 │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Cache Options ─────────────────────────────────────────────────────────────╮
│ --use-cache           Force the use of the cache, overriding any global     │
│                       setting.                                              │
│ --skip-cache          Bypass the local cache and re-calculate hashes,       │
│                       overriding any global setting.                        │
╰─────────────────────────────────────────────────────────────────────────────╯

dorsal file report

This command generates a self-contained HTML report for a single file.

Example

Run dorsal file report with a file path.

dorsal file report /path/to/your/file.pdf

You can also generate a report using the scan command with the --report option:

dorsal file scan /path/to/your/file.pdf --report

When complete, it will save the report to the default scan directory:

✅ Report saved successfully to: /home/user/.dorsal/scan_reports/file.pdf-20251030-093000.html

Options

  • Specify a custom output file name or directory:

    dorsal file report /path/to/my.zip -o "my_zip_report.html"

  • Generate the report and immediately open it in your default web browser:

    dorsal file report /path/to/image.png --open

  • Use a specific report template with --template or -t:

    dorsal file report /path/to/data.bin --template "default"

  • Run the command using the local cache (default)

    dorsal file report /path/to/your/file.pdf --use-cache

  • Run the command without using the local cache

    dorsal file report /path/to/your/file.pdf --skip-cache

CLI Docs

 Usage: dorsal file report [OPTIONS] PATH                                     

 Generates a self-contained, interactive HTML report for a single file.       

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * path      FILE  The path to the local file to generate a report for.   │
│                      [required]                                             │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --output  -o      PATH  Custom path to save the HTML report. If omitted, a  │
│                         default path in ~/.dorsal/scan/ will be used.       │
│ --template -t     TEXT  Name or path of the report template to use.         │
│                         [default: default]                                  │
│ --open                  Open the report in the default web browser after    │
│                         generation.                                         │
│ --help                  Show this message and exit.                         │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Cache Options ─────────────────────────────────────────────────────────────╮
│ --use-cache           Force the use of the cache, overriding any global     │
│                       setting.                                              │
│ --skip-cache          Bypass the local cache and re-process the file.       │
╰─────────────────────────────────────────────────────────────────────────────╯

dorsal file identify

Alias: dorsal id

This command retrieves metadata about a file from DorsalHub.

Example

Run dorsal file identifyon a file. By default, it uses a quick, sample-based hash.

dorsal file identify /path/to/my-file.pdf

The alias means you can also run this command as dorsal id:

dorsal id /path/to/my-file.pdf

If the file record is found, you will see its metadata in a panel:

🔎 Identifying file PDFSPEC.pdf...
╭────────────────────────────────────── File Identified ─────────────────────────────────────╮
│                                                                                            │
│    Hashes                                                                                  │
│       SHA-256:  3383fb2ab568ca7019834d438f9a14b9d2ccaa2f37f319373848350005779368           │
│          TLSH:  T13465D67BB4C61D6DF893CA46571C579B8B0D71533BAEA58604BDAF0AC6338029AC3F41   │
│                                                                                            │
│    File Info                                                                               │
│          Name:  PDFSPEC.pdf                                                                │
│          Size:  1 MiB                                                                      │
│    Media Type:  application/pdf                                                            │
│                                                                                            │
│    Tags                                                                                    │
│        No tags found.                                                                      │
│                                                                                            │
│    Pdf Info                                                                                │
│            author:  Tim Bienz, Richard Cohn, James R. Meehan                               │
│             title:  Portable Document Format Reference Manual (v 1.2)                      │
│           creator:  FrameMaker 5.1.1                                                       │
│          producer:  Acrobat Distiller 3.0 for Power Macintosh                              │
│           subject:  Description of the PDF file format                                     │
│          keywords:  Acrobat PDF                                                            │
│           version:  1.2                                                                    │
│        page_count:  394                                                                    │
│     creation_date:  1996-11-12T03:08:43Z                                                   │
│     modified_date:  1996-11-12T07:58:15Z                                                   │
│                                                                                            │
│                                                                                            │
╰────────────────────────────────────────────────────────────────────────────────────────────╯

If the file is not found, you will see a "Not found" message.

Options

  • Identify only using SHA-256 secure hash by passing --secure:

    dorsal file identify /path/to/your/file.pdf --secure

  • Get the result as a JSON with --json:

    dorsal file identify /path/to/your/file.pdf --json

  • Run the command using the local cache (default)

    dorsal file identify /path/to/your/file.pdf --use-cache

  • Run the command without using the local cache

    dorsal file identify /path/to/your/file.pdf --skip-cache

CLI Docs

 Usage: dorsal file identify [OPTIONS] PATH                                   

 Identifies a local file by its content hash against the DorsalHub database.  

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * path      FILE  The path to the local file to identify. [required]        │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --secure        Use SHA-256 to hash the file, instead of the default QUICK  │
│                 hash.                                                       │
│ --json          Output the full metadata as a raw JSON object to stdout for │
│                 scripting.                                                  │
│ --help          Show this message and exit.                                 │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Cache Options ─────────────────────────────────────────────────────────────╮
│ --use-cache           Force the use of the cache, overriding any global     │
│                       setting.                                              │
│ --skip-cache          Bypass the local cache and re-process the file,       │
│                       overriding any global setting.                        │
╰─────────────────────────────────────────────────────────────────────────────╯

dorsal file push

This command scans a single file and pushes its metadata to DorsalHub.

The file itself never leaves your machine.

By default, all pushed records are private and only visible to you.

Example

Push a file's metadata as a private record (the default):

dorsal file push /path/to/my-private-file.docx

On success, you'll see a confirmation:

📡 Preparing to push metadata for my-private-file.docx as a private record...
╭────────────────────────────── ✅ Push Complete ───────────────────────────────╮
│ The file record was successfully pushed to DorsalHub.                         │
│                                                                               │
│ SHA256 Hash: 3383fb2ab568ca7019834d438f9a14b9d2ccaa2f37f319373848350005779368 │
╰───────────────────────────────────────────────────────────────────────────────╯

Options

  • Push a file's metadata as a public record, making it visible to all DorsalHub users:

    dorsal file push /path/to/public-file.txt --public

  • Get the raw JSON API response after the push:

    dorsal file push /path/to/your/file.pdf --json

    dorsal file push /path/to/your/file.pdf --use-cache

  • Run the command without using the local cache

    dorsal file push /path/to/your/file.pdf --skip-cache

  • Run the command and overwrite the local cache with the result

    dorsal file push /path/to/your/file.pdf --overwrite-cache

CLI Docs

 Usage: dorsal file push [OPTIONS] PATH                                       

 Pushes a single file's metadata to DorsalHub.                                

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * path      FILE  The path to the single file to push to DorsalHub.         │
│                      [required]                                             │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --private / --public  Index the file record as private or public.           │
│                       [default: private]                                    │
│ --json                Output the API response as a raw JSON object.         │
│ --help                Show this message and exit.                           │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Cache Options ─────────────────────────────────────────────────────────────╮
│ --use-cache           Force the use of the cache, overriding any global     │
│                       setting.                                              │
│ --skip-cache          Bypass the local cache and re-process the file,       │
│                       overriding any global setting.                        │
│ --overwrite-cache     Re-process file and overwrite the local cache entry.  │
╰─────────────────────────────────────────────────────────────────────────────╯

➡️ Continue to: dorsal dir Guide