Command reference

dropoutt provides commands for scanning data, mapping coverage, inspecting checks, and preparing offline environments. Every command also works as python -m dropoutt.

dropoutt scan PATH

Scan a file or directory and write dataset reports.

Flag	Default	Meaning
--model, -m	none	Target model id, local path, or alias. Unlocks the token and loss-mask checks.
--target	none	Declare what you are building. This is what enables blocking findings and exit code 10.
--profile, -p	auto	sft, corpus, preference, or auto.
--seq-len	from model config	Training sequence length.
--tier	config, then 1	Highest check tier to run.
--out, -o	PATH/.dropoutt	Where to write artifacts.
--offline	off	Never touch the network. Resolve everything from the cache.
--limit	none	Maximum records to read from each file, for a fast look.
--no-evidence	off	Omit record excerpts and source paths from every output.
--no-html	off	Skip the HTML report.
--no-open	off	Do not open the report when the scan finishes.
--workers, -j	sized from the machine	Processes for the scan pass. Results do not depend on this value.
--brief	off	Print the verdict and one line per finding.
--quiet, -q	off	Write reports without terminal output.

dropoutt scan ./data
dropoutt scan ./data --model qwen3 --seq-len 4096
dropoutt scan ./data --target sft --quiet          # CI gate
dropoutt scan ./data --limit 1000                  # quick look at a huge corpus
dropoutt scan ./data --offline --no-evidence       # nothing fetched, nothing quoted

Worker count does not change findings, evidence samples, or the fingerprint id. Left alone, --workers reads CPU affinity, cgroup quotas, physical cores and free memory rather than os.cpu_count().

dropoutt atlas PATH

Place a sample of records on a fixed map and write atlas.html, atlas.md, and atlas.json. Atlas reports are stored beside scan reports without replacing them.

Flag	Default	Meaning
--model, --atlas	atlas-v3	The map to place on. atlas-v3 is the only one that ships; the flag lets a run say which map it meant.
--sampling, --sample	500,000	Records to place. 0 places every record. A count larger than the corpus is the same as 0.
--out, -o	PATH/.dropoutt	Where to write artifacts.
--offline	off	Never touch the network. Resolve the encoder from the cache.
--limit	none	Maximum records to read from each file.
--no-evidence	off	Omit record excerpts and source paths from every output.
--no-html	off	Skip the HTML page.
--no-open	off	Do not open the page when the run finishes.
--workers, -j	sized from the machine	Processes for the reading pass.
--quiet, -q	off	Write reports without terminal output.

dropoutt atlas ./data
dropoutt atlas ./data --sampling 500        # a quick look
dropoutt atlas ./data --sampling 0          # every record
dropoutt atlas ./data --offline             # encoder from the cache

Atlas findings are informational and do not block a build. The command exits 1 when it cannot draw a map: the encoder is unavailable, or no record has the 40 characters placement needs. A map name other than atlas-v3, on the command line or in dropoutt.toml, is a usage error rather than a silent fallback.

Additional commands

Command	What it does
dropoutt checks [ID]	List every check, or describe one: tier, requirements, the profiles it blocks under, the fix, and the reasoning.
dropoutt fetch [--model ID] [--all]	Download what a later `--offline` run needs: the atlas encoder, the tokenizer panel, and with `--model` one more tokenizer. Exits 1 if anything could not be prepared.
dropoutt models	List supported models, their chat-template families, licences, and shorthand aliases.
dropoutt benchmarks	List evaluation sets used for contamination checks and which indices ship.

Use dropoutt version or dropoutt -V for the installed version. Use dropoutt help or dropoutt -h for command help.

Exit codes

Exit codes distinguish completed runs, command failures, usage errors, and blocking findings, so a CI job never reads "found problems" and "crashed" as the same thing.

Code	Meaning
0	Command completed. Findings may be present.
1	Command failed to produce output.
2	Usage error.
10	Blocking findings were reported for the declared `--target`.

In CI

.github/workflows/data.yml

- run: pip install dropoutt
- run: dropoutt scan ./data --model qwen3 --target sft --quiet
- run: dropoutt atlas ./data --model atlas-v3 --quiet
- uses: actions/upload-artifact@v4
  with:
    name: dropoutt-report
    path: data/.dropoutt/

Add --no-evidence before uploading reports to CI when artifacts have broader access than the source data. Use --quiet to suppress terminal output or --brief to print the verdict and one line per finding.

Configuration

Place dropoutt.toml beside the data to define default options. Command-line options take precedence.

dropoutt.toml

[scan]
model = "Qwen/Qwen3-8B"
target = "sft"        # declaring a target is what enables blocking
seq_len = 4096
atlas = "atlas-v3"    # the map dropoutt atlas places on; the only one that ships
offline = true

[mute]
# Check ids to silence. Muting is a decision worth reviewing.
checks = ["T1-LIC-001"]

Offline environments

Fetch model tokenizers and the atlas encoder on a networked machine, then reuse their caches in the offline environment.

# on the login node, where there is network
export DROPOUTT_CACHE=/shared/dropoutt-cache
export HF_HOME=/shared/hf
dropoutt fetch --model qwen3

# on the compute node, where there is not
export DROPOUTT_CACHE=/shared/dropoutt-cache
export HF_HOME=/shared/hf
python -m dropoutt scan ./data --model qwen3 --offline
python -m dropoutt atlas ./data --model atlas-v3 --offline

Set both DROPOUTT_CACHE and HF_HOME in offline environments. Model tokenizers are stored under HF_HOME; the atlas encoder under DROPOUTT_CACHE.

Environment variables

Variable	Meaning
DROPOUTT_CACHE	Cache location. Holds the atlas encoder and cached tokenizer configs. Overrides `XDG_CACHE_HOME`.
DROPOUTT_OFFLINE	When `1`, `true`, `yes`, or `on`, resolve only from local files and caches.
DROPOUTT_OPEN	`0` never opens the finished report; `1` always does, ignoring the SSH and headless checks.
DROPOUTT_WORKERS	Default number of processes for the reading pass. `-j` overrides it for one run.
DROPOUTT_NO_GPU	When truthy, skip accelerator detection entirely.
DROPOUTT_DEVICE	Force the device the atlas encoder uses: `cpu`, `cuda`, or `mps`.
DROPOUTT_DEBUG	When truthy, show a traceback for an internal error instead of the concise exit-1 message.
HF_HOME	Hugging Face cache root. Tokenizers are cached here, not under `DROPOUTT_CACHE`.
HF_HUB_OFFLINE	Honoured as an offline request.

PreviousGet started NextReading the report