Command Line Reference

Obliterator is driven from the command line. This page lists each Obliterator command and the options it accepts. Options are grouped by where they apply: some belong to every remediation, some to a specific authentication mode, and some to a single provider such as IMAP or EWS.

Synopsis

.\Obliterator.exe start -p <project> --provider <provider> --auth-mode <mode> `
  -i <items.csv> [options]
.\Obliterator.exe resume -p <project> [options]
.\Obliterator.exe clear-credentials -p <project> [--team-password <password>]
.\Obliterator.exe third-party-notices

Command	Description
start	Creates or opens a project, imports the items in the input CSV, and permanently deletes them.
resume	Reopens an existing project and continues the remediation with the existing project settings.
clear-credentials	Clears the credentials stored in a project.
third-party-notices	Shows the licenses and notices of the third-party software that Obliterator includes.

The command line syntax on this page is written for PowerShell and are run from the folder where Obliterator.exe resides. A line ending in a backtick (`) continues on the next line. If you are using Command Prompt, replace each backtick with ^.

Run .\Obliterator.exe <command> --help for the options a command accepts. Running Obliterator with no arguments at all prints the help.

Option Availability by Command

Option	start	resume	clear-credentials
--project, -p	Required	Required	Required
--team-password	✓	✓	✓
--yes, -y	✓	✓
--automatic-retries	✓	✓
--log-dir	✓	✓
--verbose	✓	✓
--retry-permanent-errors		✓
Every other option on this page	✓

resume accepts only a few options because it rebuilds the rest of the remediation from the settings stored in the project. third-party-notices accepts no options.

General Rules

• Named values are not case sensitive. For example, --provider graphmail is the same as --provider GraphMail.
• A client secret, password or certificate password that is omitted is prompted for (masked) before anything is deleted, so it stays out of your shell history. Values already stored in the project are reused without asking.
• A subsequent start against an existing project uses the settings the project was created with. An option you pass that disagrees with the project is refused.
• Switches cannot be changed once a project has been created. Repeat every switch the project was created with, or start a new remediation project with the configuration you would like to use. This applies to --verify-hashes, --allow-soft-delete, --allow-identity-mismatch, --use-impersonation and --imap-use-id.

Project and Session

These options apply to every remediation, whatever the provider.

--project

Alias: -p · Value: file path · Commands: all Required

The project database (.obproj). start creates a project database if it does not exist. The project file is an encrypted database that tracks the status of every item, and it holds the credentials and OAuth token caches the remediation needs in order to be resumed.

--team-password

Value: text · Commands: all

An optional team password unique to your organization that can be used to protect the project database.

Caution

Commands issued against a project have to supply the same team password with which the project was originally created. If the team password is lost, Obliterator will not be able to resume the project.

--yes

Alias: -y · Value: switch · Commands: start, resume

Skips the confirmation prompt before deleting. Without this option, a non-interactive terminal session cannot confirm, and the remediation is refused with exit code 2.

Target and Input

These three options describe what is being remediated and how Obliterator authenticates. All three are required by start.

--provider

Value: Gmail, GoogleDrive, GraphMail, OneDrive, SharePoint, Ews, Imap · Commands: start Required

The provider where the items reside.

Provider	Service
Gmail	Gmail API
GoogleDrive	Google Drive API
GraphMail	M365 or personal Microsoft emails via Microsoft Graph
OneDrive	OneDrive through Microsoft Graph
SharePoint	SharePoint document libraries through Microsoft Graph
Ews	Exchange Web Services, on-premises Exchange or M365
Imap	Any IMAP server

--input

Alias: -i · Value: file path · Commands: start Required

The input CSV that lists the items to remediate.

--auth-mode

Value: Basic, Interactive, AppOnlySecret, AppOnlyCertificate, Dwd · Commands: start Required

How Obliterator authenticates with the provider.

Mode	Meaning
Basic	Username and password, including App Passwords.
Interactive	Modern authentication with a browser sign-in, once per target account.
AppOnlySecret	Microsoft App-only Authentication with a client ID, tenant ID and client secret.
AppOnlyCertificate	Microsoft App-only Authentication with a client ID, tenant ID and PFX certificate.
Dwd	Google domain-wide delegation using a Google service account.

Not every mode is available for every provider:

Provider	Basic	Interactive	AppOnlySecret	AppOnlyCertificate	Dwd
Gmail		✓			✓
GoogleDrive		✓			✓
GraphMail		✓	✓	✓
OneDrive		✓	✓	✓
SharePoint		✓	✓	✓
Ews	On-premises only	✓	✓	✓
Imap	✓	✓

Basic with EWS requires --ews-url, because Exchange Online has retired basic authentication. Interactive with IMAP requires --imap-oauth-provider.

Authentication Credentials

Which of these options a remediation reads depends on the provider and the authentication mode.

Option	Used by
--client-id	Interactive (every provider), AppOnlySecret, AppOnlyCertificate
--client-secret	Interactive with Gmail or Google Drive, AppOnlySecret, and the IMAP presets other than m365 and mspersonal
--tenant-id	GraphMail, OneDrive, SharePoint, Ews other than Basic, and the IMAP m365 preset
--pfx-path, --pfx-password	AppOnlyCertificate
--dwd-json	Dwd
--username, --password	Basic (IMAP and on-premises EWS)

OAuth Application

--client-id

Value: text · Commands: start

The client ID (application ID) of the OAuth application you registered with the provider: an Azure app registration for Microsoft, a Google Cloud OAuth client for Google, or a developer app for the other IMAP presets. Prompted for if omitted.

--client-secret

Value: text · Commands: start

The OAuth client secret.

• Google (Gmail, GoogleDrive, IMAP gmail preset): required. Prompted for if omitted.
• Microsoft AppOnlySecret: required. Prompted for if omitted.
• IMAP yahoo, aol, fastmail and comcast presets: prompted for if omitted, and may be left blank for an OAuth application that has no secret.
• An interactive Microsoft sign-in (GraphMail, OneDrive, SharePoint, Ews, and the IMAP m365 and mspersonal presets) has no secret, so the option is refused.

--tenant-id

Value: text · Commands: start

The Microsoft Entra tenant ID.

• App-only (AppOnlySecret, AppOnlyCertificate): required under every cloud. Prompted for if omitted.
• Interactive: optional in the commercial cloud, where it only narrows which accounts may authenticate.
• Sovereign clouds: required with --cloud GccHigh, DoD or China. A tenant ID already stored in the project satisfies this without being retyped.

It is used by GraphMail, OneDrive, SharePoint, Ews other than Basic, and the IMAP m365 preset. It is refused for Google providers, for basic authentication, and for the IMAP mspersonal preset.

Certificate

--pfx-path

Value: file path · Commands: start AppOnlyCertificate

A PFX certificate used for App-only Authentication. The certificate is stored in the project, so a later remediation session can leave this option off.

--pfx-password

Value: text · Commands: start AppOnlyCertificate

The password protecting the PFX certificate. Prompted for if omitted.

Google Domain-Wide Delegation

--dwd-json

Value: file path · Commands: start Dwd

The JSON key of a Google service account that has been granted domain-wide delegation. Required for --auth-mode Dwd unless the project already holds one.

Basic Authentication

--username

Value: text · Commands: start Basic

The username for IMAP or on-premises EWS.

• Without --use-impersonation: each account logs in as itself. The login defaults to the account’s TargetEmail, and a Username column in the input CSV overrides this option per account. Supply it only when the login differs, e.g., DOMAIN\jdoe, or jdoe for a server that requires the local part alone.
• With --use-impersonation: the one service account that acts on every mailbox. Prompted for if omitted.

--password

Value: text · Commands: start Basic

The password or App Password for IMAP or on-premises EWS.

• Without --use-impersonation: used for every account that has no password of its own. A Password column in the input CSV takes precedence per account, and an account covered by neither is prompted for by name before anything is deleted.
• With --use-impersonation: the service account’s password. Prompted for if omitted.

Note

A per-account password stored in the project takes precedence over --password on every later remediation session. To replace a password that has changed, supply the new value in the Password column of the input CSV, or run clear-credentials.

Microsoft Clouds

--cloud

Value: Commercial, GccHigh, DoD, China · Default: Commercial · Commands: start

The Microsoft Azure sovereign cloud to target.

It applies to GraphMail, OneDrive, SharePoint, Ews other than Basic, and the IMAP m365 and mspersonal presets. It is refused when typed for other providers.

Every sovereign cloud requires --tenant-id. Personal Microsoft accounts exist in the commercial cloud only, so the IMAP mspersonal preset accepts Commercial alone.

IMAP

These options apply only with --provider Imap, and are refused for any other provider.

--imap-host

Value: host name · Default: the preset’s server under Interactive · Commands: start Required for IMAP Basic

The IMAP server’s host name, e.g., imap.example.com.

• Basic: required.
• Interactive: defaults to the server of the --imap-oauth-provider preset, so it is needed only for a server the preset does not name.

Preset	Default server
gmail	imap.gmail.com
m365	The IMAP server of the selected --cloud
mspersonal	outlook.office365.com
yahoo	export.imap.mail.yahoo.com
aol	export.imap.aol.com
fastmail	imap.fastmail.com
comcast	imap.comcast.net

--imap-port

Value: 1 to 65535 · Default: 993 for Implicit, 143 otherwise · Commands: start

The IMAP server’s port. Needed only when the server does not listen on the conventional port for the chosen --imap-ssl-mode.

--imap-ssl-mode

Value: None, Implicit, Explicit · Default: Implicit · Commands: start

How the IMAP connection is secured.

Mode	Meaning
Implicit	TLS from the first byte, conventionally on port 993.
Explicit	A plain connection upgraded with STARTTLS, conventionally on port 143.
None	No transport security, for servers that offer nothing else.

--imap-use-id

Value: switch · Commands: start

Sends the IMAP ID command after connecting. Some providers, such as 163, require it.

--imap-oauth-provider

Value: gmail, m365, mspersonal, yahoo, aol, fastmail, comcast · Commands: start Required for IMAP Interactive

The modern authentication preset. Required with --auth-mode Interactive, and refused with Basic. You always supply the OAuth credentials yourself through --client-id, plus --client-secret for the presets that use one.

Preset	Authenticated by	Notes
gmail	Google SDK	A client secret is required. The account has to be set to delete expunged messages forever, which Obliterator checks before starting remediation.
m365	MSAL	Work and school Microsoft accounts. No client secret. Accepts --tenant-id and --cloud.
mspersonal	MSAL	Personal Microsoft accounts of any domain, e.g., Outlook.com, Hotmail, Live and MSN. No client secret and no tenant ID. Commercial cloud only.
yahoo, aol	Authorization code	The redirect URL defaults to oob.
fastmail, comcast	Authorization code

--oauth-redirect-url

Value: absolute URL or oob · Default: a loopback address on a free port, or oob for yahoo and aol · Commands: start

Overrides the OAuth redirect URL so it matches the one registered with your OAuth application. It applies to the yahoo, aol, fastmail and comcast presets only. It is refused with gmail, m365 and mspersonal, whose libraries register a redirect URL of their own, and everywhere outside IMAP modern authentication.

Value	Behavior
Omitted	Loopback on a free port, which Obliterator listens on. oob for yahoo and aol.
oob	The provider shows the authorization code on its own page and Obliterator prompts for it.
urn:ietf:wg:oauth:2.0:oob	The same, in Google’s spelling. Yahoo and AOL reject it.
http://localhost:8080/	Listened on, provided the port is free.
http://localhost	Obliterator prompts for the code instead of listening for it.
Any hosted URL	Obliterator prompts for the code. The whole URL from the browser’s address bar can be pasted instead.

Prompting for the code needs an interactive console. When a value other than the loopback default applies, the preflight block and the Remediation Log header both name it.

Hash Verification

--verify-hashes

Value: switch · Commands: start IMAP only

Downloads each message and compares its hash with the one recorded in the input CSV before deleting it. A message whose hash does not match is excluded from remediation. Every row of the input CSV has to carry a hash, and each is checked for the right format before the remediation starts. This option is refused for any provider other than IMAP.

--verification-hash-type

Value: Md5, Sha1, Sha256, Sha512 · Default: Sha256 · Commands: start IMAP only

The hash algorithm that was used to calculate the supplied hashes. Refused without --verify-hashes.

EWS

These options apply only with --provider Ews, and are refused for any other provider.

--ews-url

Value: URL · Default: the M365 endpoint for the selected cloud · Commands: start

The EWS endpoint of an on-premises Exchange server, e.g., https://mail.contoso.local. Omitting it targets M365. A port and scheme are honored, e.g., https://mail.contoso.local:444. The standard /EWS/Exchange.asmx path may be included, and any other path is refused.

Naming an endpoint is what makes a remediation on-premises, so it is required for --auth-mode Basic and for --use-impersonation.

--use-impersonation

Value: switch · Commands: start On-premises EWS only

Uses Exchange impersonation, so one service account is used to access every target mailbox. Requires --ews-url, and is refused for M365, where the ApplicationImpersonation role has been deprecated. Use AppOnlySecret or AppOnlyCertificate for M365 instead.

• Basic: the service account is given by --username and --password, which are prompted for if omitted.
• Interactive: the service account signs in once, and that one sign-in acts on every target mailbox.

Because one identity acts on many mailboxes by design, the identity check is not applied.

Microsoft Graph

These options apply only to GraphMail, OneDrive and SharePoint.

--allow-soft-delete

Value: switch · Commands: start GraphMail, OneDrive, SharePoint

Where the provider refuses to delete an item permanently, removes it the ordinary way instead, which leaves it recoverable in Recoverable Items or a recycle bin.

• Without it: such an item is left in place and recorded as a permanent error.
• With it: such an item is soft deleted (removed but still recoverable). It is counted separately in the summary and listed in the Soft Deleted Items Log.

A personal Microsoft account’s OneDrive has no permanent delete functionality, so it is refused without this switch and soft deleted with it. Refused for every other provider, whose deletes have no recoverable fallback.

Deletion Behavior

These options apply to every provider, with the exceptions noted.

--deletion-mode

Value: Single, Batch, Bulk · Default: Batch · Commands: start

How items are sent to the provider.

Mode	What is sent	What the provider reports
Single	One request per item.	Each item’s own result. The slowest mode.
Batch	One request targeting many items.	Each item still answered individually.
Bulk	(Gmail only) One messages.batchDelete request for up to 1,000 items that were first confirmed to exist.	Nothing per item, so every deletion is verified afterwards.

Bulk is refused for any provider other than Gmail. EWS, and SharePoint items addressed by Site alone, are always deleted one at a time.

--allow-identity-mismatch

Value: switch · Commands: start

Before remediating an account, Obliterator compares the identity it authenticated as with the account’s TargetEmail, and skips an account that does not match. Using this switch disables the identity check, which is useful for delegate access and shared mailboxes.

It is refused for an interactive Microsoft sign-in (GraphMail, OneDrive, SharePoint, Ews without --use-impersonation, and the IMAP m365 and mspersonal presets), which can act only as the account that authenticated. Use AppOnlySecret or AppOnlyCertificate to access other people’s mailboxes or drives.

Retries and Logs

--automatic-retries

Value: 0 to 100 · Default: 10 · Commands: start, resume

How many retry attempts are made for items that failed for a transient reason, such as throttling.

--retry-permanent-errors

Value: switch · Commands: resume

Retries the items previously recorded as permanent errors (e.g., permission denied) once the cause has been fixed. It applies to the first attempt only. Automatic retry attempts do not retry items with permanent errors.

.\Obliterator.exe resume -p case.obproj --retry-permanent-errors

--log-dir

Value: directory path · Default: a Logs folder beside the project · Commands: start, resume

The directory the logs are written to. It is created if needed, and refused when it names a file or a drive that is not available. Leave the option off to keep the logs beside the project.

--verbose

Value: switch · Commands: start, resume

Includes more details in the Exception Log. Turn it on when the details are needed to diagnose a problem.

Third-Party Notices

Command: third-party-notices · Options: none

Shows the licenses and notices of the third-party software Obliterator includes. The same content is published on the Third-Party Notices page.

Reading the notices does not require the EULA to have been accepted, because the licenses they reproduce grant their rights to whoever receives the software.

Help and Version

Option	Meaning
--help, -h, -?	Prints the help for the command it follows and exits with code 0.
--version	Prints the version. Accepted before a command only.

Exit Codes

Code	Meaning
0	Nothing remains. Every item was accounted for.
1	Items remain. See the Remaining Items Log.
2	Refused before remediation started. For example, a command line that could not be understood, a declined or impossible confirmation, a command line that disagrees with the project, an unusable input CSV, or an interactive Microsoft sign-in as an account other than the one the input CSV names.
3	The EULA was declined, could not be presented, or its acceptance could not be recorded.
70	An unhandled error. The Remediation Log carries an ABORTED line.
130	Cancelled with Ctrl+C.

Examples

You can find several usage examples on the Examples page.