Command-line tool for creating, extracting, listing, and rewriting Xbox ISO (XISO) disc images. Ships as XISOSharp(.exe) (see Install below).
This project is a direct conversion of the extract-xiso CLI tool (reference build 202609111233) from C to C#. It provides the same interface and produces byte-identical output for all operations, plus 40+ extra modes (Redump archival, xdvdfs parity, audit/repair/salvage, CISO/CCI, disc/DAT inspection, skeleton overlay, per-file hashes, checksums).
Version 2.1.0 adds STFS-to-ISO conversion (XISOSharp convert <package> <out.iso>: extract the package file table, then repack it as an optimized
XISO) and content-based STFS detection, including packages misnamed .iso.
Host-I/O diagnostics now recognize the FAT32 4 GB limit. The tool still
multi-targets .NET 8, .NET 9, .NET 10 and .NET 11 with C# 15. Release bundles
remain Windows .zip, Linux .tar.gz and macOS .dmg, with the net11.0
executable. The 1.9.0 feature set carries forward: disc-info,
apply-skeleton, file-hashes, verify-dat, xex-image, parallel collection
verbs, --symlink-mode, --strict-names, --deterministic, --zar-level and
actionable host-I/O diagnostics. The reviewed API cleanup removes the 1.x
StfsSharp facades; the CLI uses StfsSharp directly.
Reader probing also accepts rebuilt "sector-0" XISOs (volume descriptor at absolute offset 0, DescriptorSector = 0): extract/list/tree/info, --filetime, --sector-layout, --ranges, --copy-in, and ZAR packing all work on them. rebuild rejects them with a clear error — repack to the standard sector-32 layout first.
- SimpleXisoDrive — read-only Dokan/FUSE drive that mounts ISO/CISO and GOD/SVOD sources through
XisoImage/XisoImageSource, plus CHD and ZAR through their dedicated readers. - XISO Studio — desktop converter/explorer with GOD/SVOD input, the title metadata panel and XBE logo/title/save previews.
- StfsSharp, CCISharp and ZArchiveSharp — the standalone reader/writer packages consumed by the CLI.
# Framework-dependent build (requires the .NET 11 SDK, pinned in global.json)
dotnet build XISOSharp.Cli -c Release
# bin: XISOSharp.Cli/bin/Release/net11.0/XISOSharp.Cli(.exe)
# Self-contained trimmed single-file (no runtime needed), renamed to XISOSharp(.exe)
./publish-cli.ps1
# binaries land in publish/<rid>/XISOSharp(.exe), ~14-16 MB each
# RIDs: win-x86, win-x64, win-arm64, linux-x64, linux-arm64, osx-x64, osx-arm64
# ... or one RID manually (single-file + trimmed come from the csproj defaults)
dotnet publish XISOSharp.Cli -c Release -f net11.0 -r win-x64 --self-containedTip
Double-clicking XISOSharp.exe in Explorer prints the usage text and keeps the
window open (Press any key to exit...) instead of flashing away. The pause only
happens on an interactive no-argument launch — scripts, pipes, test hosts, and
XISO_NO_PAUSE=1 are never blocked.
On every launch the CLI compares its version against the latest GitHub release
(at most one network request per 24 hours — the result is cached under
%LocalAppData%/XISOSharp/update-check.json). When a newer release exists you get
a stderr notice with the release URL and the matching platform asset
(release_<version>_<rid>.<ext>: Windows .zip, Linux .tar.gz, macOS .dmg;
e.g. release_1.0.0_win-x64.zip), and on an interactive console you are offered
to open the release page in your browser.
[UPDATE] XISOSharp 1.0.3 is available (you have 1.0.2).
[UPDATE] Download: https://github.com/purelogiccode/XISOSharp/releases/download/1.0.3/release_1.0.3_win-x64.zip
[UPDATE] Release notes: https://github.com/purelogiccode/XISOSharp/releases/tag/1.0.3
Open the release page in your browser now? [y/N]:
Skipped (no network, no output) for -q/-Q/-v runs and under test hosts.
Set XISO_NO_UPDATE_CHECK=1 to disable the check entirely. The check never
fails the run and never files a bug report.
XISOSharp [options] [-[lrx]] <file1.xiso> [file2.xiso] ...
XISOSharp [options] -c <dir> [name] [-c <dir> [name]] ...
XISOSharp validate <source.iso> <output.iso> [options]
XISOSharp rebuild <xiso|game.zar> [video.iso] [filler|seed] [su...] -o <redump.iso>
XISOSharp build-image [sourceDir] [output.iso] -m "host:image" [-f <toml>] [-O output] [-D|--dry-run]
XISOSharp image-spec from -O <out> -m "host:image" ... [specPath]
XISOSharp compress|cso|cci <sourceDir|image> [output] [--format cso|cci]
[--ciso-level 0..9] [--ciso-version 1|2|auto] [--ciso-split bytes]
[--cci-level 0..12] [--cci-split bytes] [--batch <dir>] [--jobs <n>]
XISOSharp decompress|uncso|decso|uncci <cso|cci|god> [output.iso] [--batch <dir>]
XISOSharp checksum [--silent] <image> [images...]
XISOSharp hash <image> [images...] [--json]
XISOSharp verify-hashes <image> <hash-file> [--ignore-extra] [--json]
XISOSharp verify-dat <dat> <image> [images...] [--json]
XISOSharp file-hashes <image> [-o <file>] [--algorithm sha1|sha256|md5] [--json]
XISOSharp disc-info <image> [--json] [--sectors <sectors.txt>] [--skip-sectors <n>]
XISOSharp apply-skeleton <skeleton.xiso> <source-dir> -o <out.iso> [--hash <file>] [--strict-names]
XISOSharp xex-image <image> <path>|game.xex --type thumbnail -o <out.png>
XISOSharp split [--size <bytes|half>] [--output <base>] <image> [images...] [--batch <dir>]
XISOSharp join [--output <file>] <first.1.iso> [...]
XISOSharp convert <src.zar|src.iso|god> <out.iso|out.zar|out.cci|out.cso> [--batch <dir> --format iso|zar]
Rules: flags must precede positional arguments (the first non-flag token ends option
parsing, except the first-token verbs above). Flags match exactly — combined shorts
like -lr are NOT supported. An unknown flag is treated as a filename; a known
flag in a filename slot fails fast (must come before ISO filenames). Help is -h
or --help; both exit 0, as does -v/--version; with no arguments usage is
printed and the tool exits 1.
| Flag | Description |
|---|---|
-c <dir> [name] |
Create an ISO from <dir> (optional name overrides output, may include a path; repeatable) |
--pack <input> [name] |
Pack a directory into an ISO, or repack an existing ISO in place (rewrite) |
-x |
Extract xiso(s) (explicit; the default mode) |
--unpack <file> [dest] |
Unpack the whole image (auto-named ./<game>/ when dest omitted). XBLA/XBLIG STFS packages unpack through their file table |
-l |
List top-level entries (non-recursive); also .zar and XBLA/XBLIG STFS packages |
-t |
Tree — recursive listing with full paths, sizes, totals (ISO, .zar, STFS) |
-i <file> [path] |
Volume info + directory entry metadata (sector, size, attributes) |
--ls <file> [path] |
Flat directory listing, names only (mirrors ls) |
--md5 <file> [path] / --sha256 <file> [path] |
Hash files inside the image (whole image / directory / single file) |
--xex-info <file> <path> |
Xbox 360 XEX2 header (module flags, entry point, title ID, region, ...) plus XDBF/XSRC title name, publisher, developer, genre and description when present |
--xbe-info <file> <path> |
Original-Xbox XBEH header + certificate (title ID/name, media, region); --json adds hasLogoBitmap / hasTitleImage / hasSaveImage |
--xbe-image <file> <path> --type logo|title|save -o <out.png|out.dds> |
Extract an XBE logo, $$XTIMAGE title image or $$XSIMAGE save image as PNG or DDS |
--copy-out <iso> <path> <dest> |
Copy a file or directory out of an image |
--copy-in <iso> <host> <path> |
Patch a host file into an image (replace or add; writes <iso>.old unless --no-backup) |
-V <file1.xiso> ... |
Deep integrity audit: header, tree, sector bounds, cycles, attributes; prints Optimized: yes/no (the tag is reported, not required) |
--repair <file> |
Fix audit issues in place (.old backup; --dry-run previews; --no-backup skips) |
--salvage <file> |
Rebuild reachable entries from a corrupt image (--repair-out overrides output) |
-r |
Rewrite as optimized ISO (byte-identical to extract-xiso -r) |
validate <src> <out> |
Validate conversion between two images (+ --validate* flags; mismatch exits 2). Both sides accept ISO, CISO/CCI (single or split), split ISO sets and .zar |
checksum [images...] / --checksum |
SHA3-256 deterministic image checksum (--silent → hex only); ISO/ZAR/STFS tree hashes compare equal |
verify-dat <dat> <image>... |
Redump-style XML DAT verification (size + MD5/SHA-1/CRC32); reports verified/ambiguous/not-in-DAT/missing entries, --json |
file-hashes <image> |
Generate a per-file sidecar for ISO/split/CISO/CCI/GOD/STFS/ZAR (--algorithm sha1|sha256|md5, -o <file>, --json) |
disc-info <image> |
XGD/Redump layout inspector: XGD type/wave, video/game partitions, PFI layer break, security sectors and Redump-size warnings (--json, --sectors, --skip-sectors) |
apply-skeleton <skeleton> <dir> -o <out> |
Restore a --petrify skeleton from a source tree; verifies the optional .hash (--strict-names) |
xex-image <image> <path> --type thumbnail -o <out.png> |
Export the XDBF 0x8000 thumbnail; a loose .xex is accepted |
title-info <image> [--json] |
Root default.xbe, default.xex or default_mp.xbe title metadata (name, ID, region, disc, version); Xbox 360 XDBF adds publisher/developer/genre/description/thumbnail presence. A GOD header or its .data folder, or a single-file XBLA/XBLIG STFS package, reports XContent name/ID/disc metadata |
split / join (joinsplit) |
Split into <base>.1.iso… parts / reassemble (--size, --output, --batch; default size 0xFF000000, 4 GiB − 16 MiB) |
--filetime <image> / --set-filetime <image> <value> |
Show / set the FILETIME volume field |
--sector-layout <image> |
Full sector map: volume summary, per-file extents, used/free ranges |
--ranges <image> |
System (bone) vs file sector ranges (inclusive spans) |
--is-optimized <image> |
Print whether the image carries the optimized tag (supports --skip-sectors) |
--batch <dir> (+ --batch-recursive) |
Process all .iso in <dir> (extract/list/tree/rewrite/audit), or the verb's inputs (compress/decompress/convert/split) |
compress (cso, cci) / decompress (uncso, decso, uncci) |
CISO v2 LZ4 (default) / v1 DEFLATE, CCI LZ4 and GOD/SVOD round-trip (--format, --ciso-*, --cci-*, --batch) |
convert |
ZArchive to ISO / ISO to ZArchive / GOD to ISO, CCI or CISO (--batch --format iso|zar for whole directories) |
build-image / image-spec |
xdvdfs-parity ordered packing from globs / TOML spec generation |
--video / --random / --seed / --wipe / --trim / --petrify / --update / --zar |
Redump archival verbs (--jobs/--policy for --zar; --all/--best/--compress aliases; --security-sectors for rebuild) |
rebuild |
Rebuild a lossless Redump image from components (-o <redump.iso>) |
| Flag | Description |
|---|---|
-d <directory> |
Extract: output directory. Rewrite: directory for the rewritten ISO |
-D |
Rewrite: delete old xiso after processing. build-image: dry-run alias |
-h |
Print help and exit (the ONLY help flag) |
-m |
Disable automatic .xbe media-enable patching (create/rewrite; not recommended) |
-n, --no |
Never overwrite: refuse when an output exists (cannot combine with -y) |
-y, --yes |
Always overwrite without prompting |
-o <filename> |
Custom output filename (rewrite/rebuild/compress); relative or rooted paths used as-is |
-q |
Quiet (suppress non-error output) |
-Q |
Silent (suppress all output) |
-s |
Skip $SystemUpdate folder (create: implies -X "**/$SystemUpdate/**") |
-v, --version |
Print the version banner plus XISOSharp/CCISharp/ZArchiveSharp/runtime/commit details and exit |
-X <glob> |
Create mode only: exclude files/dirs by glob (repeatable; / separator, case-insensitive) |
--skip-sectors N |
Filesystem starts N sectors into the file (Redump video partition); extract/list/tree/rewrite/unpack/filetime |
--prepend-sectors N |
Write N empty sectors before the filesystem (create/rewrite) |
--layout <file> |
Create/--pack/build-image: pack at fixed sectors from a --sector-layout --json file or a path=sector text spec; unlisted entries are first-fit |
--preserve-attrs |
Rewrite: keep source RO/HID/SYS/NOR bits instead of DIR/ARC defaults |
--file-time <value> |
Fixed volume FILETIME on create/pack/build-image (ISO-8601, decimal, 0x hex, now, 0 = deterministic) |
--deterministic |
Alias for --file-time 0; accepted for create, --pack, rewrite and build-image |
--strict-names |
Fail before writing when a component exceeds the Xbox 42-character limit or is outside Latin-1 (default warns) |
--skip-existing |
Extract/unpack/copy-out: skip files already on disk with matching sizes (resume). Batch verbs: skip sources whose output exists |
--continue-on-error |
Extract/unpack/copy-out: log per-file failures and continue (still exits non-zero). Batch verbs: keep converting after a failure |
--name-policy reject|sanitize|skip |
Extract/unpack: handle host-unsafe entry names (default reject; sanitize renames with collision-safe ~N; skip omits the entry/subtree). Applies to ISO/CISO/CCI/GOD/ZAR/STFS extraction |
--delete-source |
Batch verbs only: delete each source after a successful conversion (requires -y; refused with -n; split sets delete every part) |
--output-name <template> |
Batch verbs only: name outputs from {name}, {ext} and {format} (e.g. "{name}.xiso.{format}") |
--no-backup |
Skip the <iso>.old backup (copy-in/repair only) |
--dry-run |
Preview --repair fixes without changing anything (repair only) |
--repair-out <path> |
Salvage output override (salvage only) |
--validate / --validate-checksums / --validate-strict / --validate-report <file> |
Post-rewrite/conversion validation (require -r or validate) |
--ciso-level 0..9 / --ciso-version 1|2|auto / --ciso-split <bytes> |
CISO codec options (compress only) |
--format cso|cci / --cci-level 0..12 / --cci-split <bytes> |
CCI output and codec options (compress only): 0 stores raw, 1..9 use fast LZ4, 10..12 use managed LZ4-HC. |
--jobs <n> / --policy <skip|overwrite|auto-rename> |
Parallel + overwrite handling for --zar; batch verbs accept --jobs 1..64; single-file CISO/CCI compress accepts --jobs 1..64 for sector compression (byte-identical output); extract (-x) and --unpack accept --jobs 1..64 to copy independent files in parallel (byte-identical, ordered FileAdded progress); multi-image checksum, hash, -V, -l, -t and -r process images in parallel with identical output |
--symlink-mode <follow|skip|reject> |
Create-time link policy for -c, --pack, build-image and apply-skeleton (follow is the historical behavior) |
--zar-level <1..22> |
zstd level for --zar, --compress and convert --format zar (default 6 stays byte-identical) |
--security-sectors <file> (--sectors) |
Rebuild-only security-sector range override |
-f <toml> / -m "host:image" (--map) / -O <out> (--output) |
build-image/image-spec inputs |
--json |
Machine-readable output for read-only verbs (-i, -l, -t, checksum, hash, verify-hashes, verify-dat, file-hashes, disc-info, title-info, --sector-layout, --ranges, --filetime, --xex-info, --xbe-info, validate, -v). JSON on stdout, human logs on stderr |
| Code | Meaning |
|---|---|
0 |
Success; -h; -v; validate passed; audit passed; empty image (ErrIsoNoFiles is success) |
1 |
Any error: usage, flag values, mode conflicts, open failures, invalid ISO |
2 |
Validation mismatch (validate command or -r --validate) |
# Extract / list / audit
XISOSharp -d ./out game.iso
XISOSharp --unpack game.iso ./out
XISOSharp -t game.iso
XISOSharp -V game1.iso game2.iso
# Resume an interrupted unpack
XISOSharp --skip-existing --unpack game.iso ./out
# Create (skip updates + temp files, custom name)
XISOSharp -s -X "**/*.tmp" -c ./game_files custom.iso
# Pack / repack / rewrite
XISOSharp --pack ./game_files
XISOSharp --pack game.iso
XISOSharp -r --validate --validate-strict game.iso
# Redump-style round-trip (game partition at the XGD2 offset)
XISOSharp -c --prepend-sectors 129824 ./game_files redump.iso
XISOSharp --skip-sectors 129824 -d ./out redump.iso
# Copy out / patch in / hashes / headers
XISOSharp --copy-out game.iso /media ./media_out
XISOSharp --copy-in game.iso ./my-config.ini /config.ini
XISOSharp --sha256 game.iso
XISOSharp --xbe-info game.iso /default.xbe
XISOSharp title-info game360.iso
XISOSharp --xbe-image game.iso /default.xbe --type title -o title.png
# Sector map, sector ranges, optimized-tag probe
XISOSharp --sector-layout game.iso
XISOSharp --ranges game.iso
XISOSharp --is-optimized game.iso
# Repack at an existing image's sector layout (JSON or path=sector text)
XISOSharp --sector-layout --json game.iso > game.layout.json
XISOSharp -c ./game_files game.iso --layout game.layout.json
XISOSharp --pack ./game_files game.iso --layout layout.txt
# Batch a folder of ISOs
XISOSharp --batch ./isos -d ./extracted
XISOSharp -r --batch ./isos --batch-recursive
# Archival (Redump) - plain ISOs only; decompress/convert/join containers first
XISOSharp --video game.redump.iso
XISOSharp --best game.redump.iso
XISOSharp --zar -o game.zar game.iso
XISOSharp rebuild x.iso video.iso filler.bin su20076000_00000000 -o rebuilt.redump.iso
# xdvdfs parity
XISOSharp build-image ./src -m "bin:/" -m "assets/**:/assets/{1}" -O out.iso
XISOSharp compress game.iso game.cso --ciso-level 9
XISOSharp decompress game.cso game.iso
XISOSharp compress --format cci game.iso game.cci --cci-split 0
XISOSharp decompress game.1.cci game.iso
XISOSharp checksum game.iso
XISOSharp checksum game.zar
XISOSharp checksum game.stfs
XISOSharp validate --validate-checksums game.zar game.iso
XISOSharp convert game.zar game.iso
XISOSharp -l game.stfs # XBLA/XBLIG STFS package
XISOSharp -x -d game game.stfs # extract the package file table
XISOSharp -l "4D5307E6" # GOD header (or its .data folder)
XISOSharp decompress "4D5307E6" game.iso # GOD -> ISO
XISOSharp convert "4D5307E6" game.cci # GOD -> CCI
XISOSharp split --size half --output base game.iso
XISOSharp join --output rejoined.iso base.1.iso
# Batch container conversion
XISOSharp compress --batch ./isos --format cci --cci-split 0 -y
XISOSharp decompress --batch ./compressed --skip-existing -y
XISOSharp convert --batch ./isos --format zar -y
XISOSharp split --batch ./isos --size half -y
XISOSharp compress --batch ./isos --output-name "{name}.xiso.{format}" --jobs 4 -y
XISOSharp compress --batch ./isos --delete-source -y # delete sources after success
# Machine-readable output (stdout JSON, stderr logs)
XISOSharp -i --json game.iso
XISOSharp -l --json game.iso | ConvertFrom-Json
XISOSharp checksum --json game.iso game.cci
XISOSharp validate --json game.iso rewritten.iso
XISOSharp -v --jsonEvery mode, option matrix, restriction table, and deep-dive lives in the
CLI Reference. New additions beyond extract-xiso (audit,
repair/salvage, unpack/batch/pack, copy-in/out, hashes, XEX/XBE parsing,
Redump archival, xdvdfs parity) are listed there and in the
main README.
MIT