CLI Options

This page is the main reference for the current CLI surface.

For accepted value formats such as time deltas, ranges, booleans, and profile --set values, see Value Formats.

Command Tree

The primary cleanup command is:

dmd clean ...

Other top-level commands are:

• dmd login
• dmd logout
• dmd whoami
• dmd list guilds
• dmd list channels
• dmd list profiles
• dmd cache clear
• dmd profile fields
• dmd profile show
• dmd profile add
• dmd profile update
• dmd profile remove

Cleanup Command

Scope and safety

Short	Long	Default	Description
-d	--dry-run	off	Simulate deletions without making changes. Uses a separate .dryrun.json preserve cache file when preserve-cache is enabled.
-i	--include-ids	all eligible	Restrict processing to matching full IDs or unique ID suffixes.
-x	--exclude-ids	none	Exclude matching full IDs or unique ID suffixes from processing.
-	--profile	unset	Load cleanup defaults from a named profile in config.json. Explicit CLI flags still win.
-t	--token	unset	Override stored credentials and DISCORD_TOKEN for this command only.

Retention

Short	Long	Default	Description
-n	--keep-last	0	Keep the last N messages in each channel.
-	--keep-last-scope	all	Count keep-last against all recent messages in the channel (all) or only your deletable messages (mine).
-k	--keep-within	0	Keep messages and reactions newer than this time delta.
-	--keep-reactions	off	Keep your reactions instead of deleting them during cleanup.
-	--preserve-cache	off	Persist kept message IDs between runs.
-	--preserve-cache-path	~/.config/delete-me-discord/preserve_cache.json	Override the preserve cache path.

Fetch and execution

Short	Long	Default	Description
-f	--fetch-within	unlimited	Fetch only messages newer than this time delta.
-m	--max-messages	unlimited	Maximum number of messages to fetch per channel.
-	--buffer-per-channel	off	Buffer one channel at a time before evaluation.
-	--fetch-sleep-time	0.2 0.4	Sleep between fetch requests. One value is fixed, two define a random range in seconds.
-	--delete-sleep-time	1.5 2	Sleep between delete actions. One value is fixed, two define a random range in seconds.

Timing and retries

Short	Long	Default	Description
-	--max-retries	5	Maximum retry attempts for retryable API requests.
-	--retry-time-buffer	25 35	Extra wait after rate limits. One value is fixed, two define a random range in seconds.

Output

Short	Long	Default	Description
-q	--quiet	off	Only show warnings and errors.
-v	--verbose	0	Increase output detail. Repeat for more verbosity.
-j	--json	off	Emit JSON output for logs and discovery output.
-r	--redact-sensitive [SUFFIX] or [PREFIX SUFFIX]	off	Redact sensitive values in logs and discovery output.
-	--redact-names / --no-redact-names	on	Redact human-readable names when sensitive redaction is enabled.
-V	--version	n/a	Show the version and exit.

Discovery Commands

Guild listing

dmd list guilds lists guild IDs and names available to the authenticated user.

Channel listing

dmd list channels lists channels grouped by guild/category/parent plus DMs.

Profile listing

dmd list profiles lists the configured cleanup profile names from config.json.

dmd list guilds and dmd list channels support:

• --token
• --config-path
• --include-ids
• --exclude-ids
• --json
• --quiet
• --verbose
• --redact-sensitive
• --redact-names / --no-redact-names
• retry flags

--include-ids and --exclude-ids accept full Discord IDs or unique ID suffixes. Suffixes are resolved against discovered guild, category, guild text channel, DM, and Group DM IDs before filtering.

dmd list profiles supports:

• --config-path
• --json
• --quiet
• --verbose
• --redact-sensitive
• --redact-names / --no-redact-names

Authentication Commands

Login

dmd login ensures a token is stored in the system keyring. If a keyring token already exists, it validates that token and exits without prompting. If an old plaintext token exists, it migrates that token to the keyring and removes the plaintext copy. If no stored token exists, it prompts for one interactively.

Use dmd login --replace to prompt for a new token and replace the stored keyring token.

Logout

dmd logout removes the stored token from the system keyring and deletes any old plaintext token.

Identity Check

dmd whoami shows which account the active token belongs to.

Cache Management

dmd cache clear

Deletes the active preserve cache file.

You can override the path with:

dmd cache clear --preserve-cache-path /path/to/cache.json

Profile Management

Profile commands are useful once you want saved cleanup presets.

Fields

dmd profile fields lists supported stored field names, expected value types, and whether none is allowed. See Value Formats for accepted --set values.

Show

dmd profile show <name> prints the stored profile exactly as it exists in config.json.

Add

dmd profile add <name> --set key=value ... creates a new profile.

Examples:

• dmd profile add nightly-dms --set include_ids=123456789012345678 --set keep_within=2w
• dmd profile add nightly-dms --set include_ids=490059 --set keep_within=2w
• dmd profile add nightly-dms --set preserve_cache=true

When include_ids or exclude_ids are set, profile commands resolve full IDs or unique suffixes through Discord before writing config.json. Stored profiles contain full IDs. Because that validation calls Discord, profile add and profile update also accept --token, --config-path, and retry flags.

Update

dmd profile update <name> --set key=value ... --unset field1 field2 ... changes an existing profile.

Examples:

• dmd profile update nightly-dms --set verbose=2
• dmd profile update nightly-dms --unset fetch_within max_messages
• dmd profile update nightly-dms --set max_messages=none

Remove

dmd profile remove <name> deletes a stored profile entry.

dmd profile fields, show, add, update, and remove support:

• --config-path
• --json
• --quiet
• --verbose
• --redact-sensitive

Important Flags

Keep Last

--keep-last keeps the last N messages in each channel.

Examples:

• --keep-last 20
• --keep-last 0

Keep Last Scope

--keep-last-scope controls how --keep-last is counted.

• all: count all recent messages in the channel
• mine: count only your deletable messages

The default is all.

Keep Within

--keep-within keeps messages and reactions newer than a given time delta, measured backwards from the time the command runs.

Examples:

• --keep-within 2w
• --keep-within "1w3d"
• --keep-within "0"

See Value Formats for the full time delta syntax.

Fetch Within

--fetch-within limits how much history is fetched from each channel, measured backwards from the time the command runs.

This improves speed, but it also means the tool only sees a slice of history unless you widen the fetch window or use preserve-cache strategically.

If a profile defines a fetch window and you want to remove it for one run, use:

• --fetch-within none

Buffered Mode

--buffer-per-channel fetches one channel into memory before evaluation instead of walking it lazily.

Use this when you want stronger per-channel timing visibility in a manual run and do not mind the extra per-channel buffering cost.

If a profile defines a message limit and you want to remove it for one run, use:

• --max-messages none

Boolean Overrides

Boolean clean flags support explicit negative forms as well.

Examples:

• --dry-run / --no-dry-run
• --keep-reactions / --no-keep-reactions
• --preserve-cache / --no-preserve-cache
• --buffer-per-channel / --no-buffer-per-channel
• --quiet / --no-quiet
• --json / --no-json
• --redact-names / --no-redact-names

This matters most when a profile enables one of these options and you want to turn it off for a single run.

Sensitive Redaction

--redact-sensitive redacts sensitive values in normal CLI logs, JSON logs, and discovery output. -r is the short alias.

Examples:

• --redact-sensitive
• --redact-sensitive 4
• --redact-sensitive 0 4
• --redact-sensitive 4 4
• -r 4 --no-redact-names

For dmd list guilds and dmd list channels, this redacts guild names, channel names, category names, DM names, and IDs. Use --no-redact-names when you want names to stay visible while IDs remain redacted.

Here, “names” means Discord display names used to identify targets and accounts:

• authenticated username
• guild names
• category names
• channel names
• DM and Group DM display names

See Value Formats for profile redaction values.

See also

• Profiles
• Value Formats
• Preserve Cache
• Log Output