{"id":36941182,"url":"https://github.com/lazaroagomez/wusbkit","last_synced_at":"2026-03-17T06:00:10.984Z","repository":{"id":326980100,"uuid":"1106601162","full_name":"lazaroagomez/wusbkit","owner":"lazaroagomez","description":"Windows USB device toolkit - CLI for listing, inspecting, and managing USB drives","archived":false,"fork":false,"pushed_at":"2025-12-03T20:27:08.000Z","size":84,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T20:36:23.421Z","etag":null,"topics":["go","usb","windows"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lazaroagomez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2025-11-29T15:17:40.000Z","updated_at":"2025-12-03T18:38:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lazaroagomez/wusbkit","commit_stats":null,"previous_names":["lazaroagomez/wusbkit"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/lazaroagomez/wusbkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lazaroagomez%2Fwusbkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lazaroagomez%2Fwusbkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lazaroagomez%2Fwusbkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lazaroagomez%2Fwusbkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lazaroagomez","download_url":"https://codeload.github.com/lazaroagomez/wusbkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lazaroagomez%2Fwusbkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28620574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T23:49:58.628Z","status":"ssl_error","status_checked_at":"2026-01-20T23:47:29.996Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["go","usb","windows"],"created_at":"2026-01-13T10:48:44.864Z","updated_at":"2026-03-17T06:00:10.969Z","avatar_url":"https://github.com/lazaroagomez.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wusbkit\n\nA fast, native Windows CLI toolkit for USB drive management. Zero external dependencies — all operations use direct Win32 APIs (WMI, DeviceIoControl, VDS, fmifs).\n\n## Features\n\n- **List** all connected USB storage devices (native WMI, sub-200ms)\n- **Flash** disk images to USB drives (.img, .bin, .iso, .raw)\n- **Create** disk images from USB drives (ImageUSB-compatible .bin format)\n- **Format** USB drives (FAT32, NTFS, exFAT) — FAT32 bypasses Windows 32GB limit\n- **Eject** USB drives safely\n- **Set volume labels** without reformatting\n- **Parallel operations** — flash, format, or label multiple drives simultaneously\n- **Streaming decompression** — flash from .gz, .xz, .zst files without extracting\n- **Remote flashing** — stream images directly from HTTP/HTTPS URLs\n- **Write verification** — read back and compare after flashing\n- **SHA-256 hashing** — calculate hash during write\n- **Skip-unchanged sectors** — faster partial updates\n- **Write retry logic** — 3 retries with 1s delay on failure (matches ImageUSB behavior)\n- **Pre-write speed test** — detects fake/unresponsive drives before flashing\n- **ImageUSB .bin header support** — auto-detects headers, verifies checksums\n- **ISO bootable USB** — detects bootloader (GRUB2, Syslinux, Windows), writes MBR\n- **Partition extension** — grow NTFS partition after flashing smaller images\n- **BitLocker detection** — warns before operating on encrypted drives\n- **JSON output** — all commands support `--json` for programmatic integration\n- **Disk locking** — prevents concurrent operations on the same drive\n- **Signal handling** — graceful cancellation with Ctrl+C\n\n## Requirements\n\n- Windows 10 or later (64-bit)\n- Administrator privileges (for format, flash, and create operations)\n\n\u003e **No PowerShell required.** All operations use native Windows APIs.\n\n## Installation\n\n### From Releases\n\nDownload `wusbkit.exe` from the [latest release](https://github.com/lazaroagomez/wusbkit/releases).\n\n### From Source\n\n```bash\ngit clone https://github.com/lazaroagomez/wusbkit.git\ncd wusbkit\ngo build -o dist/wusbkit.exe .\n```\n\n## Quick Start\n\n```bash\n# List USB drives\nwusbkit list\n\n# Flash an image (ChromeOS, Ubuntu, Raspberry Pi, etc.)\nwusbkit flash 2 --image recovery.bin --yes --verify --hash\n\n# Flash to multiple drives at once\nwusbkit flash 2,3,4 --image ubuntu.img --parallel --yes\n\n# Create a backup image from USB\nwusbkit create E: --output backup.bin\n\n# Format as FAT32 (works on drives \u003e 32GB)\nwusbkit format 2 --fs fat32 --label \"USB\" --yes\n\n# Eject safely\nwusbkit eject E:\n```\n\n## Commands\n\n### `list` — List USB Drives\n\n```bash\nwusbkit list              # Table output\nwusbkit list -v           # Verbose (serial, VID/PID, filesystem, hub port)\nwusbkit list --json       # JSON array\n```\n\n### `info` — Drive Details\n\n```bash\nwusbkit info E:           # By drive letter\nwusbkit info 2            # By disk number\nwusbkit info E: --json    # JSON output\n```\n\n### `flash` — Write Image to USB\n\n```bash\n# Local files\nwusbkit flash 2 --image ubuntu.img --yes\nwusbkit flash E: --image recovery.bin --verify --hash\n\n# Compressed (streaming decompression)\nwusbkit flash 2 --image ubuntu.img.xz --yes\nwusbkit flash 2 --image raspios.img.gz --yes\nwusbkit flash 2 --image arch.img.zst --yes\n\n# From URL (streams without downloading)\nwusbkit flash 2 --image https://example.com/image.img --yes\n\n# Parallel flash (same image to multiple drives)\nwusbkit flash 2,3,4,5 --image ubuntu.img --parallel --yes\nwusbkit flash 2-6 --image recovery.bin --parallel --max-concurrent 3 --yes\n\n# All options\nwusbkit flash 2 --image file.img --yes --verify --hash --skip-unchanged --buffer 8M\n```\n\n**Supported sources:** `.img`, `.bin`, `.iso`, `.raw`, `.gz`, `.xz`, `.zst`, `.zip`, HTTP/HTTPS URLs\n\n### `create` — Create Image from USB\n\n```bash\nwusbkit create E: --output backup.bin --yes\nwusbkit create 2 --output D:\\images\\chromeos.bin --yes --json\n```\n\nCreates an ImageUSB-compatible `.bin` file with a 512-byte header containing MD5 and SHA1 checksums. A companion `.log` file is generated alongside the image.\n\n### `format` — Format USB Drive\n\n```bash\nwusbkit format 2 --fs fat32 --yes                        # FAT32 (no 32GB limit)\nwusbkit format E: --fs ntfs --label \"DATA\" --yes          # NTFS\nwusbkit format 2 --fs exfat --yes                         # exFAT\nwusbkit format 2,3,4 --fs fat32 --parallel --yes          # Parallel\n```\n\n| Filesystem | Max File Size | Cross-Platform | Notes |\n|------------|--------------|----------------|-------|\n| FAT32 | 4 GB | Excellent | Custom formatter bypasses Windows 32GB limit |\n| NTFS | 16 EB | Windows | Full permissions support |\n| exFAT | 16 EB | Good | Large files + cross-platform |\n\n### `eject` — Safely Eject\n\n```bash\nwusbkit eject E:          # By drive letter\nwusbkit eject 2           # By disk number\nwusbkit eject E: --yes    # Skip confirmation\n```\n\n### `label` — Set Volume Label\n\n```bash\nwusbkit label E: --name \"BACKUP\"\nwusbkit label E,F,G --name \"USB\" --parallel     # Multiple drives\n```\n\n\u003e Does not require administrator privileges for USB drives.\n\n### `version` — Show Version\n\n```bash\nwusbkit version\nwusbkit version --json\n```\n\n## Global Flags\n\n| Flag | Short | Description |\n|------|-------|-------------|\n| `--json` | `-j` | JSON output for programmatic use |\n| `--verbose` | `-v` | Verbose output |\n| `--no-color` | | Disable colored output |\n\n## Multi-Disk Syntax\n\nAll parallel commands accept flexible disk specifications:\n\n| Syntax | Example | Meaning |\n|--------|---------|---------|\n| Single | `2` or `E:` | One drive |\n| List | `2,3,4` | Specific drives |\n| Range | `2-6` | Drives 2 through 6 |\n| Mixed | `2,4-6,8` | Drives 2, 4, 5, 6, 8 |\n\n## JSON API\n\nAll commands support `--json` for integration with external tools.\n\n- **stdout**: JSON data and NDJSON progress streams\n- **stderr**: JSON error objects `{\"error\": \"...\", \"code\": \"...\"}`\n- **Exit 0**: Success, **Exit 1**: Error\n\n### Error Codes\n\n| Code | Description |\n|------|-------------|\n| `USB_NOT_FOUND` | Device not found |\n| `FORMAT_FAILED` | Format operation failed |\n| `FLASH_FAILED` | Flash operation failed |\n| `PERMISSION_DENIED` | Admin privileges required |\n| `INVALID_INPUT` | Invalid arguments |\n| `DISK_BUSY` | Another operation in progress |\n| `INTERNAL_ERROR` | Unexpected error |\n\n### Progress Streaming (NDJSON)\n\nFlash and format operations emit line-delimited JSON progress:\n\n```json\n{\"stage\":\"Writing\",\"percentage\":45,\"bytes_written\":2348810240,\"total_bytes\":5170026496,\"speed\":\"48.2 MB/s\",\"status\":\"in_progress\"}\n{\"stage\":\"Verifying\",\"percentage\":90,\"bytes_written\":4653023846,\"total_bytes\":5170026496,\"speed\":\"52.1 MB/s\",\"status\":\"in_progress\"}\n{\"stage\":\"Complete\",\"percentage\":100,\"status\":\"complete\",\"hash\":\"c7425a15...\"}\n```\n\nParallel operations emit per-disk events:\n\n```json\n{\"type\":\"start\",\"diskNumber\":2,\"operation\":\"flash\"}\n{\"type\":\"complete\",\"diskNumber\":2,\"success\":true,\"duration\":\"1m45s\"}\n{\"type\":\"summary\",\"total\":4,\"succeeded\":4,\"failed\":0}\n```\n\n## Architecture\n\n```\nwusbkit/\n├── cmd/                    # CLI commands (Cobra)\n│   ├── create.go           # create command\n│   ├── eject.go            # eject command (IOCTL_STORAGE_EJECT_MEDIA)\n│   ├── flash.go            # flash command\n│   ├── format.go           # format command\n│   ├── label.go            # label command (SetVolumeLabelW)\n│   ├── list.go             # list command\n│   ├── info.go             # info command\n│   └── version.go          # version command\n├── internal/\n│   ├── disk/               # Native Win32 disk operations\n│   │   ├── ioctl.go        # DeviceIoControl wrappers\n│   │   ├── format_fat32.go # Custom FAT32 formatter (BPB + FAT tables)\n│   │   ├── format_vds.go   # NTFS/exFAT via fmifs.dll + VDS COM\n│   │   ├── extend.go       # Partition extension and creation\n│   │   ├── bitlocker.go    # BitLocker detection (WMI)\n│   │   └── volume.go       # Volume label operations\n│   ├── flash/              # Image flashing\n│   │   ├── flash.go        # Flash orchestration + retry + speed test\n│   │   ├── source.go       # Image sources (file, zip, URL, compressed, .bin)\n│   │   └── writer.go       # Raw disk writer + buffer pooling\n│   ├── format/             # Format orchestration\n│   │   └── format.go       # High-level format pipeline\n│   ├── image/              # ImageUSB .bin format\n│   │   ├── header.go       # 512-byte header codec\n│   │   └── create.go       # USB-to-image creation\n│   ├── iso/                # ISO bootable USB pipeline\n│   │   ├── pipeline.go     # ISO write orchestrator\n│   │   ├── bootloader.go   # Bootloader detection + MBR writing\n│   │   └── mbr/            # Embedded MBR templates (GRUB2, Syslinux, Windows)\n│   ├── encoding/           # Shared encoding utilities\n│   │   └── utf16le.go      # UTF-16LE codec\n│   ├── usb/                # USB device enumeration\n│   │   ├── device.go       # Device data models\n│   │   ├── enumerate.go    # Enumeration with caching\n│   │   ├── enumerate_native.go  # Native WMI (parallel queries)\n│   │   └── location_windows.go  # USB hub port via cfgmgr32\n│   ├── parallel/           # Parallel operations\n│   │   └── executor.go     # Batch format/flash/label with NDJSON\n│   ├── lock/               # Disk locking\n│   │   └── disklock.go     # File-based cross-process locks\n│   └── output/             # Display helpers\n│       ├── json.go         # JSON output + error codes\n│       └── table.go        # pterm table formatters\n└── main.go                 # Entry point\n```\n\n## How It Works\n\nAll disk operations use **native Windows APIs** — no PowerShell, no diskpart, no external processes:\n\n| Operation | API Used |\n|-----------|----------|\n| Device enumeration | WMI (Win32_DiskDrive, MSFT_Partition) |\n| Raw disk I/O | CreateFileW + ReadFile/WriteFile (unbuffered, 4KB aligned) |\n| Volume locking | FSCTL_LOCK_VOLUME + FSCTL_DISMOUNT_VOLUME |\n| Partition creation | IOCTL_DISK_CREATE_DISK + IOCTL_DISK_SET_DRIVE_LAYOUT_EX |\n| FAT32 formatting | Custom sector writer (BPB, FSInfo, FAT tables) |\n| NTFS/exFAT formatting | fmifs.dll FormatEx (VDS COM fallback) |\n| Partition extension | IOCTL_DISK_GROW_PARTITION + FSCTL_EXTEND_VOLUME |\n| Eject | IOCTL_STORAGE_EJECT_MEDIA |\n| Volume label | SetVolumeLabelW |\n| BitLocker detection | WMI (Win32_EncryptableVolume) |\n| Hub port location | cfgmgr32.dll (DEVPKEY_Device_LocationInfo) |\n\n## License\n\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flazaroagomez%2Fwusbkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flazaroagomez%2Fwusbkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flazaroagomez%2Fwusbkit/lists"}