Command-line reference

The promptdust binary is a thin, read-only front end over the engine. It discovers where AI tools store data on this machine and reports what amplifies the exposure. It never modifies files, sends nothing off the device unless you opt in, and never issues a verdict.

Running promptdust with no arguments is the same as promptdust scan.

scan

Scan this machine for AI-data stores. This is the default command.

promptdust scan

Flag	Effect
--json	Emit the machine-readable JSON document instead of the table. With --json, standard output is pure JSON and warnings go to standard error.
--only <ids/tools>	Only scan these definition ids or tool names (comma-separated).
--exclude <ids/tools>	Skip these definition ids or tool names (comma-separated).
--path <subtree>	Restrict findings to a subtree of your machine.
--no-slow	Skip the slow shell-out probes (Time Machine exclusion, disk encryption). Faster, at the cost of two amplifier inputs.
--large-threshold <bytes>	The byte threshold above which a store trips the large_growth amplifier.
--output <file>	Also write the report to a file. A .json or .html extension picks the format.

Examples:

promptdust scan --json                  # machine-readable, for scripting or diffing runs
promptdust scan --only cursor           # just one tool
promptdust scan --only claude-code,cursor
promptdust scan --path ~/code           # only stores under a subtree
promptdust scan --no-slow               # skip Time Machine and disk-encryption checks
promptdust scan --output report.json    # write a report (it is sensitive)

Writing a report prints a “store it carefully” warning to standard error, because the file maps where sensitive AI data lives on your machine.

diagnostics

Produce a redacted, path-free bundle to paste into a bug report. It contains only counts, versions, and OS information. No file paths and no conversation content, so it is safe to share. It prints a “review before sharing” note to standard error.

promptdust diagnostics
promptdust diagnostics --no-slow

telemetry

Manage opt-in, anonymous usage telemetry. It is off by default and there is no live backend yet. See Telemetry for the exact payload and the guarantees.

promptdust telemetry status     # enabled or disabled, plus whether the environment forces it off
promptdust telemetry enable     # opt in
promptdust telemetry disable    # opt out (the default)
promptdust telemetry preview    # print the exact anonymous payload; sends nothing

telemetry preview accepts --no-slow like scan.

definitions

Inspect the definition database (the catalog of where tools store data).

promptdust definitions list             # every tool PromptDust knows how to find
promptdust definitions list --json      # the public catalog as JSON (the website's data contract)
promptdust definitions validate <file>  # validate a definition JSON file

version

Print the tool version and the definition-database version.

promptdust version

Environment variables

These control the optional feedback features. None of them affect a scan, which is always local-only.

Variable	Effect
DO_NOT_TRACK	Any non-empty, non-0 value forces telemetry off and suppresses the local crash report. Follows the consoledonottrack.com convention.
PROMPTDUST_TELEMETRY	A kill-switch. A falsy value (0, false, no, off) forces telemetry off. A truthy value does not turn it on; only telemetry enable does.
PROMPTDUST_NO_CRASH_REPORT	Suppresses even the writing of a local crash report.
CI	When set, telemetry never runs and no crash artifact is written.

Exit codes

0 on success. 1 when a definitions validate file is invalid. 2 for a usage or environment error, such as a home directory that cannot be determined or a report file that cannot be written.