Sherlock Output Formats: Configuring CSV, XLSX, and Text Reports

Sherlock supports three primary output formats—plain text, CSV, and XLSX—each activated via dedicated command-line flags defined in sherlock_project/sherlock.py.

When using the sherlock-project/sherlock tool to enumerate usernames across social networks, you can export findings in multiple structured formats. Understanding these Sherlock output formats and their configuration options enables integration with automated workflows and data analysis pipelines.

Supported Export Formats

Sherlock implements three distinct export methods within its main entry point, controlled through specific CLI arguments parsed at lines 24-30 of sherlock_project/sherlock.py.

Plain Text (Default)

By default, Sherlock generates .txt files without requiring explicit format flags. According to lines 33-42 in sherlock_project/sherlock.py, the application automatically assigns filenames using the pattern {username}.txt. When querying multiple users, this creates one text file per username in the current working directory.

CSV Format

For spreadsheet-compatible data, use the --csv flag (argument definition at lines 72-76). The implementation block spanning lines 53-95 opens a comma-separated values file, writes a header row, and appends one record per discovered site. This format respects the --folderoutput directory path constructed at lines 55-60.

Excel XLSX Format

Modern Excel workbooks require the --xlsx flag (defined at lines 78-83) and the optional pandas dependency. The code at lines 96-135 aggregates results into Python lists, constructs a pandas.DataFrame, and invokes DataFrame.to_excel to generate the final workbook. Without pandas installed, this functionality raises an ImportError.

Output Configuration Options

Beyond selecting formats, Sherlock provides granular control over file destinations and naming conventions.

Custom File Paths with --output

For single-user queries, override the default {username}.txt naming convention using the --output or -o flag (lines 66-70). This assigns result_file = args.output (lines 33-35), directing output to your specified filesystem path regardless of the username queried.

Directory Organization with --folderoutput

When processing multiple usernames, use --folderoutput or -fo (lines 60-64) to consolidate results into a single directory. The script automatically creates missing directories via os.makedirs (lines 37-39) and prepends this path to all generated filenames, ensuring clean batch operations.

Explicit Text Generation with --txt

The --txt flag (lines 89-94) maintains backward compatibility by forcing text file creation even when CSV or XLSX formats are requested. This triggers the write block at lines 43-52, which specifically handles username output to text files alongside other formats.

Command-Line Examples

# Default: Generate USERNAME.txt files

sherlock alice bob

# Single user with custom output path

sherlock -o /tmp/single_user_report.txt alice

# CSV format with dedicated output folder

sherlock --csv -fo ./sherlock_reports alice bob

# Excel workbook (requires pandas)

sherlock --xlsx alice

# Multiple formats simultaneously

sherlock --csv --txt alice

Implementation Details

The export system relies on QueryResult and QueryStatus objects defined in sherlock_project/result.py, which provide the structured data written to each format. After argument parsing, the main execution loop (lines 24-30) branches to format-specific handlers:

• Text handling: Lines 33-52 manage both default output and explicit TXT generation
• CSV handling: Lines 53-95 implement comma-separated value writing with header management
• XLSX handling: Lines 96-135 convert result lists into pandas DataFrames for Excel export

Each handler checks args.folderoutput to determine whether to prepend a custom directory to the generated filename.

Summary

• Sherlock outputs data in plain text, CSV, and XLSX formats via --txt, --csv, and --xlsx flags
• Use --output to specify custom filenames for single-user queries
• Organize batch results using --folderoutput or -fo with automatic directory creation
• XLSX generation requires the pandas library installed in your Python environment
• The --txt flag ensures text output when simultaneously generating other formats
• All export logic resides in sherlock_project/sherlock.py with specific handlers at lines 33-95

Frequently Asked Questions

Does Sherlock support JSON output?

No, the current implementation in sherlock_project/sherlock.py does not include JSON export functionality. The supported formats are limited to plain text (via default behavior or --txt), CSV (via --csv), and XLSX (via --xlsx) as implemented in the master branch.

Why does XLSX export fail with a ModuleNotFoundError?

Excel output requires the pandas library, which is an optional dependency. Install it using pip install pandas before invoking the --xlsx flag. The code at lines 96-135 explicitly relies on pandas.DataFrame and DataFrame.to_excel methods to construct the workbook.

Can I generate multiple format outputs simultaneously?

Yes, flags can be combined to produce multiple file types from a single query. For example, sherlock --csv --txt alice generates both alice.csv and alice.txt. The --txt flag ensures text file generation alongside other formats, maintaining backward compatibility as defined at lines 89-94.

How do I redirect all batch results to a specific folder?

Use the --folderoutput or -fo flag followed by your target directory path. When scanning multiple usernames, Sherlock automatically creates the directory using os.makedirs (lines 37-39) and places all result files inside it, preserving the standard naming conventions for each format.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}