{"id":46456445,"url":"https://github.com/nikosalonen/deletepy","last_synced_at":"2026-03-06T01:58:56.163Z","repository":{"id":168539995,"uuid":"629396347","full_name":"nikosalonen/deletepy","owner":"nikosalonen","description":"Batch delete/block etc. users from auth0","archived":false,"fork":false,"pushed_at":"2026-02-12T17:41:31.000Z","size":883,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-12T17:42:23.806Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nikosalonen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-04-18T08:23:04.000Z","updated_at":"2026-02-12T16:38:10.000Z","dependencies_parsed_at":"2025-05-14T13:26:29.237Z","dependency_job_id":"f319c310-85df-409e-b210-92674f2276d0","html_url":"https://github.com/nikosalonen/deletepy","commit_stats":null,"previous_names":["nikosalonen/deletepy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nikosalonen/deletepy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikosalonen%2Fdeletepy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikosalonen%2Fdeletepy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikosalonen%2Fdeletepy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikosalonen%2Fdeletepy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nikosalonen","download_url":"https://codeload.github.com/nikosalonen/deletepy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikosalonen%2Fdeletepy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30158601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T22:39:40.138Z","status":"ssl_error","status_checked_at":"2026-03-05T22:39:24.771Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-06T01:58:55.500Z","updated_at":"2026-03-06T01:58:56.155Z","avatar_url":"https://github.com/nikosalonen.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DeletePy - Auth0 User Management Tool\n\n![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/nikosalonen/deletepy?utm_source=oss\u0026utm_medium=github\u0026utm_campaign=nikosalonen%2Fdeletepy\u0026labelColor=171717\u0026color=FF570A\u0026link=https%3A%2F%2Fcoderabbit.ai\u0026label=CodeRabbit+Reviews)\n\nA comprehensive Python tool for managing Auth0 users with support for bulk operations across development and production environments. DeletePy provides safe, rate-limited operations for user management, session control, identity management, and domain validation with a modern modular architecture.\n\n## Features\n\n### Core User Operations\n\n- **Delete users** - Permanently remove users from Auth0 with all associated data\n- **Block users** - Prevent users from logging in while preserving their data\n- **Revoke sessions** - Force logout from all active sessions (Enterprise plan required)\n- **Revoke application grants** - Invalidate all authorized applications and refresh tokens\n\n### Advanced Operations\n\n- **Identity unlinking** (`unlink-social-ids`) - Smart social identity management:\n  - Unlinks social identities from multi-identity users\n  - Deletes users with only the matching social identity\n  - Protects users with Auth0 as main identity\n- **Revoke-only mode** (`revoke-grants-only`) - Revoke sessions and grants without blocking/deleting\n- **Block status checking** (`check-unblocked`) - Identify users who are not currently blocked\n- **Domain validation** (`check-domains`) - Check email domains against blocklists with optional bulk actions\n- **Data export** (`export-last-login`) - Export user last login data to timestamped CSV files\n- **Email fetching** (`fetch-emails`) - Fetch email addresses for given Auth0 user IDs and export to CSV\n- **Credential testing** (`doctor`) - Validate Auth0 API credentials and permissions\n\n### Dry-Run Preview\n\n- **Safe preview mode** (`--dry-run`) - Preview what would happen without executing operations\n- **Comprehensive analysis** - Shows success rates, potential issues, and user categorization\n- **User state detection** - Identifies already blocked users, invalid IDs, and API errors\n- **Multiple user detection** - Warns about emails with multiple Auth0 accounts\n- **Smart categorization** - For social unlink operations, shows what would be deleted vs unlinked\n- **Interactive confirmation** - After preview, choose whether to proceed with actual operation\n- **Error resilience** - Preview continues even if some API calls fail, showing partial results\n\n### Input \u0026 Safety Features\n\n- **Multiple input formats** - Support for Auth0 user IDs, email addresses, or social media IDs\n- **CSV preprocessing** - Convert multi-column CSV files to single-column input using cleanup utilities\n- **Email resolution** - Automatically resolve emails to Auth0 user IDs with multi-user detection\n- **Environment separation** - Separate development and production configurations\n- **Production safeguards** - Explicit confirmation required for production operations\n- **Advanced rate limiting** - Built-in delays to respect Auth0 API limits\n- **Progress tracking** - Real-time progress indicators for bulk operations\n- **Graceful shutdown** - Handle interruption signals safely\n- **Memory efficient** - Generator-based file processing for large datasets\n- **Robust error handling** - Comprehensive exception handling with detailed error reporting\n\n### Checkpoint \u0026 Recovery\n\n- **Automatic checkpointing** - All operations create recovery points automatically\n- **Interruption recovery** - Resume operations from exactly where they left off\n- **Progress preservation** - Never lose work on large datasets or long-running operations\n- **Production ready** - Robust handling of network failures, system restarts, and interruptions\n- **Zero configuration** - Works automatically without any setup or maintenance\n\n## Architecture\n\nDeletePy follows a modern modular architecture for maintainability and scalability:\n\n```text\ndeletepy/\n├── src/\n│   └── deletepy/\n│       ├── cli/                 # Command-line interface\n│       │   ├── main.py          # Click-based CLI entry point\n│       │   ├── commands.py      # Operation handlers\n│       │   └── validators.py    # Argument validation\n│       ├── core/                # Core functionality\n│       │   ├── auth.py          # Auth0 authentication\n│       │   ├── auth0_client.py  # Unified Auth0 API client\n│       │   ├── config.py        # Configuration management\n│       │   └── exceptions.py    # Custom exceptions\n│       ├── operations/          # Business operations\n│       │   ├── user_ops.py      # Core user operations\n│       │   ├── batch_ops.py     # Batch processing \u0026 social ID search\n│       │   ├── export_ops.py    # Export functionality\n│       │   └── domain_ops.py    # Domain checking\n│       ├── utils/               # Utilities\n│       │   ├── file_utils.py    # File operations\n│       │   ├── display_utils.py # Progress/output formatting\n│       │   ├── request_utils.py # Batch processing utilities\n│       │   └── auth_utils.py    # Authentication utilities\n│       └── models/              # Data models\n├── tests/                       # Test suite\n├── legacy files (main.py, etc.) # Backward compatibility\n└── pyproject.toml              # Modern Python packaging\n```\n\n### Key Benefits\n\n- **Modular design** - Clear separation of concerns for easier maintenance\n- **Type safety** - Comprehensive type hints throughout the codebase\n- **Modern CLI** - Click-based command-line interface with better UX\n- **Backward compatibility** - Legacy CLI still works with deprecation warnings\n- **Test coverage** - Comprehensive test suite with module-based mocking\n\n## Prerequisites\n\n- **Python 3.11+** - The tool requires Python 3.11 or higher\n- **[uv](https://docs.astral.sh/uv/)** - Fast Python package installer and resolver (recommended)\n- Auth0 account with appropriate API permissions\n- Auth0 Management API access\n\n### Installing uv\n\nuv is an extremely fast Python package installer and resolver, written in Rust. It's the recommended way to manage DeletePy. **Bonus:** uv can also automatically download and manage Python versions for you!\n\n**For macOS (easiest with Homebrew):**\n\n```bash\nbrew install uv\n```\n\n**For macOS/Linux (standalone installer):**\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n**For Windows:**\n\n```powershell\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\n**Alternative methods:**\n\n- With pip: `pip install uv`\n\nSee [uv documentation](https://docs.astral.sh/uv/getting-started/installation/) for more options.\n\n### Python Version Management\n\n**With uv (recommended):**\n\nuv can automatically download and manage Python versions for you:\n\n```bash\n# List available Python versions\nuv python list\n\n# Install a specific Python version (e.g., Python 3.14)\nuv python install 3.14\n\n# Install the minimum required version\nuv python install 3.11\n\n# Use a specific Python version when creating the environment\nuv sync --python 3.14 --extra dev\n```\n\n**Alternative version managers:**\n\nIf you prefer traditional version managers:\n\n- **macOS:** [pyenv](https://github.com/pyenv/pyenv) or [Homebrew](https://brew.sh/) (`brew install python`)\n- **Windows:** [pyenv-win](https://github.com/pyenv-win/pyenv-win) or [Python.org](https://www.python.org/downloads/)\n- **Linux:** [pyenv](https://github.com/pyenv/pyenv) or [asdf](https://asdf-vm.com/)\n\n## Installation\n\n### Quick Start with uv (Recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/nikosalonen/deletepy\ncd deletepy\n\n# (Optional) Install a specific Python version with uv\nuv python install 3.14\n\n# Install dependencies with uv (creates .venv automatically)\nuv sync --extra dev\n\n# Or use a specific Python version\nuv sync --python 3.14 --extra dev\n\n# Verify setup\nuv run deletepy doctor dev\n```\n\n**That's it!** You can now use `uv run deletepy` for all commands.\n\n### Using Makefile (Recommended)\n\nThe Makefile provides convenient shortcuts for common tasks:\n\n```bash\n# Install dependencies\nmake sync-dev          # Install with dev dependencies (recommended)\nmake sync              # Install production dependencies only\n\n# Run the tool\nmake run ARGS=\"doctor dev\"\nmake run ARGS=\"users block users.txt dev --dry-run\"\n\n# Development tasks\nmake test              # Run tests\nmake lint              # Check code quality\nmake format            # Format code\nmake type-check        # Run type checking\nmake check-all         # Run all quality checks\n\n# Upgrade dependencies\nmake upgrade           # Upgrade all dependencies and sync\n```\n\n### Alternative: Traditional pip Installation\n\nIf you prefer not to use uv, you can still use pip:\n\n1. Clone the repository and create virtual environment:\n\n   ```bash\n   git clone https://github.com/nikosalonen/deletepy\n   cd deletepy\n   python3 -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n\n2. Install in development mode:\n\n   ```bash\n   pip install -e \".[dev]\"\n   ```\n\n### Logging Configuration\n\nDeletePy defaults to Rich-powered console logging when available. You can control logging via environment variables:\n\n```bash\n# Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)\nexport DELETEPY_LOG_LEVEL=INFO\n\n# Log format (rich [default], console, detailed, json)\nexport DELETEPY_LOG_FORMAT=rich\n\n# Use structured JSON logging\nexport DELETEPY_LOG_STRUCTURED=false\n```\n\nSee `docs/LOGGING.md` for full details.\n\n### Environment Configuration\n\nCreate a `.env` file with your Auth0 credentials:\n\n```bash\n# Production credentials\nCLIENT_ID=your_prod_client_id_here\nCLIENT_SECRET=your_prod_client_secret_here\nAUTH0_DOMAIN=your_auth0_domain_here\nURL=your_custom_domain_here\n\n# Development credentials\nDEV_CLIENT_ID=your_dev_client_id_here\nDEV_CLIENT_SECRET=your_dev_client_secret_here\nDEV_AUTH0_DOMAIN=your_dev_auth0_domain_here\nDEV_URL=your_dev_custom_domain_here\n```\n\nThere's also a `.env.example` file that you can use as a template.\n\n## Usage\n\n### Command Line Interface\n\nAll commands can be run with `uv run deletepy` or directly as `deletepy` if you've activated the virtual environment.\n\n**With uv (recommended):**\n\n```bash\n# Check authentication configuration\nuv run deletepy doctor [dev|prod]\n\n# Check if specified users are unblocked\nuv run deletepy check-unblocked users.txt [dev|prod]\n\n# Check email domains for specified users\nuv run deletepy check-domains users.txt [dev|prod]\n\n# Export user last_login data to CSV\nuv run deletepy export-last-login emails.txt [dev|prod] [--connection CONNECTION]\n\n# Fetch email addresses for given user IDs and export to CSV\nuv run deletepy fetch-emails user_ids.txt [dev|prod]\n\n# Find users by social media IDs (unlinks identities or deletes users)\nuv run deletepy unlink-social-ids social_ids.txt [dev|prod] [--dry-run]\n\n# User management operations\nuv run deletepy users block users.txt [dev|prod] [--dry-run]\nuv run deletepy users delete users.txt [dev|prod] [--dry-run]\nuv run deletepy users revoke-grants-only users.txt [dev|prod] [--dry-run]\n```\n\n**With Makefile:**\n\n```bash\n# Run any command using make\nmake run ARGS=\"doctor dev\"\nmake run ARGS=\"users block users.txt dev --dry-run\"\nmake run ARGS=\"export-last-login emails.txt prod\"\n```\n\n**Direct (if virtual environment is activated):**\n\n```bash\ndeletepy doctor dev\ndeletepy users block users.txt dev --dry-run\n```\n\n## Checkpoint System\n\nDeletePy includes a comprehensive checkpoint system that automatically creates recovery points for all major operations. This ensures you can safely resume interrupted operations and never lose progress on large datasets.\n\n### Automatic Checkpointing\n\n**All operations now use checkpoints by default** - no additional configuration needed:\n\n```bash\n# These operations automatically create checkpoints\ndeletepy users delete large_dataset.txt prod\ndeletepy export-last-login emails.txt dev\ndeletepy check-unblocked users.txt prod\ndeletepy unlink-social-ids social_ids.txt dev\n```\n\n**Benefits:**\n\n- ✅ **Interruption Safe** - Safely handle Ctrl+C, network failures, or system restarts\n- ✅ **Progress Preservation** - Never lose work on large operations\n- ✅ **Automatic Resume** - Operations can be resumed from exactly where they left off\n- ✅ **Production Ready** - Robust handling of long-running operations\n- ✅ **Zero Configuration** - Works automatically without any setup\n\n### Managing Checkpoints\n\n#### List Checkpoints\n\n```bash\n# List all checkpoints\ndeletepy checkpoint list\n\n# List with detailed information\ndeletepy checkpoint list --details\n\n# Filter by operation type\ndeletepy checkpoint list --operation-type export-last-login\ndeletepy checkpoint list --operation-type batch-delete\n\n# Filter by status\ndeletepy checkpoint list --status active\ndeletepy checkpoint list --status completed\ndeletepy checkpoint list --status failed\n\n# Filter by environment\ndeletepy checkpoint list --env prod\ndeletepy checkpoint list --env dev\n\n# Combine filters\ndeletepy checkpoint list --status active --env prod --details\n```\n\n#### Resume Operations\n\n```bash\n# Resume from a specific checkpoint\ndeletepy checkpoint resume checkpoint_20241217_142830_export_last_login_dev\n\n# Resume with a different input file (optional)\ndeletepy checkpoint resume checkpoint_id --input-file new_users.txt\n```\n\n**Resume Examples:**\n\n```bash\n# Export operation was interrupted\n$ deletepy export-last-login emails.txt dev\nProcessed 1,500/5,000 emails...\n^C Operation interrupted. Resume with:\n  deletepy checkpoint resume checkpoint_20241217_142830_export_last_login_dev\n\n# Resume the export\n$ deletepy checkpoint resume checkpoint_20241217_142830_export_last_login_dev\nResuming export_last_login operation from checkpoint...\nResuming from email 1,501/5,000...\n```\n\n#### Checkpoint Details\n\n```bash\n# Show detailed information about a specific checkpoint\ndeletepy checkpoint details checkpoint_20241217_142830_export_last_login_dev\n```\n\n**Sample Output:**\n\n```text\n📋 Checkpoint Details\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n🆔 Checkpoint ID: checkpoint_20241217_142830_export_last_login_dev\n📊 Operation: export_last_login\n🔄 Status: active\n🌍 Environment: dev\n📅 Created: 2024-12-17 14:28:30\n🔄 Updated: 2024-12-17 14:35:15\n📁 Input File: /path/to/emails.txt\n📄 Output File: users_last_login_20241217_142830.csv\n\n📈 Progress Information\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n🎯 Completion: 30.0% (1,500/5,000 items)\n✅ Success Rate: 95.5% (1,433/1,500 processed)\n📦 Current Batch: 30/100\n📋 Batch Size: 50\n\n📊 Processing Results\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n✅ Processed: 1,433\n⏭️  Skipped: 45\n❌ Errors: 22\n🔍 Not Found: 35\n👥 Multiple Users: 10\n\n▶️ Resumable: Yes\n```\n\n### Checkpoint Cleanup\n\n#### Clean Completed Checkpoints\n\n```bash\n# Clean all completed checkpoints (regardless of age)\ndeletepy checkpoint clean --completed\n\n# Preview what would be cleaned\ndeletepy checkpoint clean --completed --dry-run\n```\n\n#### Clean Failed Checkpoints\n\n```bash\n# Clean only failed checkpoints\ndeletepy checkpoint clean --failed\n```\n\n#### Clean Old Checkpoints\n\n```bash\n# Clean checkpoints older than 30 days (default)\ndeletepy checkpoint clean\n\n# Clean checkpoints older than 7 days\ndeletepy checkpoint clean --days-old 7\n\n# Preview cleanup\ndeletepy checkpoint clean --days-old 14 --dry-run\n```\n\n#### Clean All Checkpoints (Use with Caution)\n\n```bash\n# Clean ALL checkpoints - use with extreme caution\ndeletepy checkpoint clean --all\n\n# Preview before cleaning all\ndeletepy checkpoint clean --all --dry-run\n```\n\n#### Delete Specific Checkpoint\n\n```bash\n# Delete a specific checkpoint with confirmation\ndeletepy checkpoint delete checkpoint_20241217_142830_export_last_login_dev\n\n# Delete without confirmation prompt\ndeletepy checkpoint delete checkpoint_id --confirm\n```\n\n### When Checkpoints Are Created\n\nCheckpoints are automatically created for these operations:\n\n| Operation | Checkpoint Type | Use Case |\n|-----------|----------------|----------|\n| `deletepy users delete` | `batch_delete` | User deletion operations |\n| `deletepy users block` | `batch_block` | User blocking operations |\n| `deletepy users revoke-grants-only` | `batch_revoke_grants` | Grant/session revocation |\n| `deletepy export-last-login` | `export_last_login` | Data export operations |\n| `deletepy fetch-emails` | `fetch_emails` | Email fetching operations |\n| `deletepy check-unblocked` | `check_unblocked` | Status checking operations |\n| `deletepy unlink-social-ids` | `social_unlink` | Identity management operations |\n\n### Storage and File Management\n\n- **Location**: Checkpoints are stored in `.checkpoints/` directory\n- **Format**: JSON files with structured metadata and progress tracking\n- **Backups**: Automatic backup files created during updates (`.backup` extension)\n- **Cleanup**: Automatic cleanup of backup files when checkpoints are deleted\n- **Size**: Checkpoint files are typically small (1-10KB) but scale with dataset size\n\n### Advanced Features\n\n#### Production Safety with Checkpoints\n\n- Checkpoints preserve environment information to prevent cross-environment resume\n- Production checkpoints require the same safety confirmations when resumed\n- Failed production operations can be safely resumed after fixing underlying issues\n\n#### Error Recovery\n\n- Failed operations create checkpoints with error details for debugging\n- Resume operations can handle partial failures and continue processing\n- Graceful handling of network issues and API errors\n\n#### Performance Optimization\n\n- Batch processing state is preserved across interruptions\n- Optimal batch sizes are maintained when resuming\n- Rate limiting state is reset appropriately on resume\n\n## Preparing Input Files\n\n### CSV Cleanup Utility\n\nIf you have a CSV file with columns like `ip,userId,userName,user_name_prefix,user_name_suffix`, use the built-in cleanup-csv command:\n\n```bash\n# Basic cleanup\ndeletepy cleanup-csv\n\n# With specific output type\ndeletepy cleanup-csv --output-type=email\ndeletepy cleanup-csv --output-type=username\ndeletepy cleanup-csv --output-type=user_id\n\n# With environment for Auth0 API resolution\ndeletepy cleanup-csv ids.csv dev --output-type=email\ndeletepy cleanup-csv ids.csv prod --output-type=username\n```\n\n**Enhanced Features:**\n\n- **Output type control** - Specify identifier type: `user_id`, `email`, or `username`\n- **Smart column detection** - Automatically finds the best column\n- **Auth0 API integration** - Resolves encoded usernames when environment is specified\n- **Rate limiting** - Proper API call throttling to prevent 429 errors\n\n### Input File Formats\n\n1. **User Management Files** - Auth0 user IDs or email addresses:\n\n   ```text\n   auth0|123456789\n   user@example.com\n   ```\n\n2. **Social ID Files** - Social media IDs for identity management:\n\n   ```text\n   10157490928027692\n   115346286307134396784\n   ```\n\n3. **Email Files** - Email addresses for domain checking or export:\n\n   ```text\n   user1@example.com\n   user2@company.org\n   ```\n\n4. **User ID Files** - Auth0 user IDs for email fetching:\n\n   ```text\n   auth0|123456789\n   google-oauth2|987654321\n   facebook|555666777\n   ```\n\n## Operation Details\n\n### Social Identity Management (`unlink-social-ids`)\n\nDeletePy provides sophisticated social identity management:\n\n- **Single Identity Users**: Users with only the matching social identity are deleted entirely\n- **Multi-Identity Users**: Only the matching social identity is unlinked, preserving the user account\n- **Detached Identity Cleanup**: After unlinking, if a user has no remaining identities, the user is automatically deleted\n- **Detached Social User Deletion**: Separate user accounts that have the unlinked social ID as their primary identity are automatically deleted\n- **Protected Users**: Users with Auth0 as main identity are protected from deletion\n- **Production Safety**: Explicit confirmation required with operation counts\n\nExample workflow:\n\n1. Provide a file with social media IDs (Facebook, Google, LinkedIn, etc.)\n2. DeletePy searches Auth0 for users with those identities\n3. Categorizes users based on their identity configuration\n4. Performs safe unlinking or deletion based on user type\n5. Automatically deletes users who become orphaned (no remaining identities) after unlinking\n6. Searches for and deletes any separate user accounts that have the unlinked social ID as their primary identity\n\n### Domain Checking (`check-domains`)\n\n1. Fetches email addresses for each user in the input file\n2. Checks each domain against blocklist APIs\n3. Categorizes results: BLOCKED, ALLOWED, UNRESOLVABLE, INVALID, ERROR\n4. Provides summary with counts for each category\n5. For blocked domains, prompts for bulk block/revoke action\n\n### Data Export (`export-last-login`)\n\n1. Processes email addresses from input file in configurable batches\n2. Resolves emails to Auth0 user IDs with comprehensive error handling\n3. Fetches user details including last_login timestamps\n4. Exports to timestamped CSV with columns: email, user_id, last_login, created_at, updated_at, status\n5. Handles edge cases: NOT_FOUND, MULTIPLE_USERS, ERROR_FETCHING_DETAILS\n6. Automatic batch size optimization based on dataset size\n\n### Email Fetching (`fetch-emails`)\n\n1. Processes Auth0 user IDs from input file in configurable batches\n2. Fetches email addresses for each user ID with comprehensive error handling\n3. Exports to timestamped CSV with columns: user_id, email, status\n4. Handles edge cases: NOT_FOUND, ERROR_FETCHING\n5. Automatic batch size optimization based on dataset size\n6. Supports checkpoint recovery for interrupted operations\n\n### Dry-Run Preview Operations\n\nDeletePy includes comprehensive dry-run preview functionality for all destructive operations:\n\n#### User Operations Preview (`--dry-run`)\n\n```bash\n# Preview blocking users\ndeletepy users block users.txt dev --dry-run\n\n# Preview deleting users\ndeletepy users delete users.txt prod --dry-run\n\n# Preview revoking grants\ndeletepy users revoke-grants-only users.txt dev --dry-run\n```\n\n**Preview Information Includes:**\n\n- **Success Analysis**: Number of users that would be processed successfully\n- **Success Rate**: Percentage of successful operations\n- **User Categorization**:\n  - ✅ Valid users that would be processed\n  - ⚠️ Users already in target state (e.g., already blocked)\n  - ❌ Invalid user IDs or malformed identifiers\n  - ❌ Users not found (emails that don't exist in Auth0)\n  - ⚠️ Emails with multiple users (requires manual resolution)\n  - ❌ API errors or network issues\n- **Detailed User Information**: Connection type, current blocked status, last login\n- **Interactive Confirmation**: Choose whether to proceed after preview\n\n#### Social Unlink Preview (`--dry-run`)\n\n```bash\n# Preview social identity operations\ndeletepy unlink-social-ids social_ids.txt dev --dry-run\n```\n\n**Social Preview Shows:**\n\n- **Users to Delete**: Users where the social ID is their only/main identity\n- **Identities to Unlink**: Users with multiple identities where only the social identity will be removed\n- **Protected Users**: Users with Auth0 as main identity (will be skipped)\n- **Detailed Reasoning**: Why each user falls into their category\n- **Operation Counts**: Total numbers for each type of operation\n\n#### Preview Benefits\n\n1. **Risk Reduction**: See exactly what will happen before execution\n2. **Data Validation**: Identify invalid inputs or missing users early\n3. **Scope Verification**: Confirm you're targeting the right users\n4. **Error Detection**: Find API issues or authentication problems before bulk operations\n5. **Performance Estimation**: Understand how long the actual operation will take\n6. **Compliance**: Review operations for audit trails in sensitive environments\n\n### Production Safety\n\n- All production operations require explicit confirmation\n- Clear warnings about irreversible actions\n- Separate credential sets prevent accidental cross-environment operations\n- Detailed operation summaries before execution\n- **Dry-run recommended** for all production operations\n\n## API Permissions\n\nThe tool requires appropriate Auth0 Management API scopes:\n\n- `read:users` - for user lookups and identity management\n- `delete:users` - for user deletion\n- `update:users` - for user blocking\n- `delete:sessions` - for session revocation (Enterprise plan)\n- `delete:grants` - for application grant revocation\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Install with development dependencies\nuv sync --extra dev\n\n# Or using make\nmake sync-dev\n```\n\n### Running Tests\n\n```bash\n# Run all tests (with uv)\nuv run pytest\n\n# Or using make (automatically uses uv if available)\nmake test\n\n# Run with coverage\nmake test-coverage\n\n# Run specific test file\nuv run pytest tests/test_auth.py\n```\n\n### Code Quality\n\n```bash\n# Format code\nmake format\n# or: uv run ruff format src/ tests/\n\n# Lint code\nmake lint\n# or: uv run ruff check src/ tests/\n\n# Fix auto-fixable issues\nmake lint-fix\n# or: uv run ruff check src/ tests/ --fix\n\n# Type checking\nmake type-check\n# or: uv run mypy src/\n\n# Run all quality checks\nmake check-all\n```\n\n### Pre-commit Hooks\n\n```bash\n# Install pre-commit hooks\nmake install-pre-commit\n# or: uv run pre-commit install\n\n# Update hooks\nmake update-pre-commit\n# or: uv run pre-commit autoupdate\n```\n\n## Technical Notes\n\n### Rate Limiting \u0026 Performance\n\n- Advanced rate limiting with exponential backoff prevents API throttling\n- Memory-efficient generator-based processing for large datasets\n- Automatic batch size optimization for export operations\n- Graceful handling of interruption signals\n\n### Error Handling\n\n- Comprehensive exception hierarchy for structured error handling\n- Detailed error reporting with color-coded output\n- Automatic cleanup of temporary files\n- Multiple user detection for email addresses with connection details\n\n### Session \u0026 Grant Management\n\n- **Session revocation** logs users out of all Auth0 SSO/browser sessions\n- **Grant revocation** invalidates all refresh tokens and prevents new access tokens\n- **Access tokens** already issued remain valid until they expire\n- Grant revocation now handles refresh token invalidation automatically\n\n## Migration from Legacy CLI\n\nThe legacy CLI (`main.py`) continues to work with deprecation warnings. To migrate to the modern CLI:\n\n1. Replace `python main.py` with `deletepy`\n2. Use the new command structure with subcommands\n3. Update any scripts or automation to use the new syntax\n\n## Contributing\n\n1. Follow the established module boundaries\n2. Maintain test coverage at 100%\n3. Use type hints throughout\n4. Follow the function complexity guidelines (max 50 lines per function)\n5. Run code quality checks before submitting PRs\n\n## License\n\n[Add your license information here]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikosalonen%2Fdeletepy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikosalonen%2Fdeletepy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikosalonen%2Fdeletepy/lists"}