Skip to content

cli.md

Latest commit

 

History

History
703 lines (584 loc) · 60.8 KB

cli.md

File metadata and controls

703 lines (584 loc) · 60.8 KB
Raw

CLI Reference

The XISOSharp command-line tool mirrors the original C tool's interface and adds a number of modern conveniences — Redump archival (XboxKit parity) and xdvdfs parity (build-image, CISO, checksum). This page is the complete reference: syntax, modes, options, validation flags, exit codes, and batch behavior.

Syntax

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] [su20076000_00000000] -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> [output.iso] [--batch <dir>]
XISOSharp checksum [--silent] <image> [images...]
XISOSharp --checksum <image> [--silent]            # flag form
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 title-info <image> [--json]
XISOSharp disc-info <image> [--json] [--sectors <sectors.txt>] [--skip-sectors <n>]
XISOSharp apply-skeleton <skeleton.xiso> <source-dir> -o <out.iso> [--hash <file>]
XISOSharp xbe-image <image> <path> --type logo|title|save -o <out.png|out.dds>
XISOSharp xex-image <image> <path> --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> <out.iso|out.zar> [--batch <dir> --format iso|zar]
  • Flags must precede positional arguments; the first non-flag token ends option parsing (except verbs above which are detected as first token).
  • Flags are matched exactly — combined shorts such as -lr are not supported.
  • An unknown flag is treated as a filename (it will then fail with an "open error"); a known flag in a filename slot fails fast with must come before ISO filenames (see Misplaced flags).
  • -h/--help print help; -v/--version print the banner (XISOSharp v<version> for <platform> - https://github.com/purelogiccode/XISOSharp) plus component/runtime/commit details; all exit 0. A --help token after the first filename is refused by the misplaced-flag guard (must come before ISO filenames).

Tab completion for PowerShell, bash, zsh and fish plus the xisosharp(1) man page are in Shell Completions & Man Page.

  • stdout/stderr are always UTF-8, independent of the host console code page, so Latin-1 filenames such as café.txt render and pipe identically on every platform.
  • With no arguments at all, usage is printed and the tool exits 1. On an interactive double-click launch (Explorer, no redirection) the window additionally waits for a keypress (Press any key to exit...) instead of closing; scripts, pipes, and XISO_NO_PAUSE=1 never pause.

Modes

Modes are mutually exclusive unless noted as aliases. If no mode is given, extract is the default.

Image inputs accept .cso/.1.cso, .cci/.1.cci and GOD header/.data sources directly (auto-detected by extension, header content or a magic-sniff fallback, xdvdfs img.rs parity): extract, --unpack, -l/-t, --pack (iso→rewrite), -r, and checksum all operate on the decompressed view, with outputs named after the game stem (game.cso → game.iso, extract dir game/; a GOD source uses its header title). Split plain-ISO sets (game.1.iso) are also read directly. .zar archives are accepted by -l, -t, -x, --unpack, checksum and validate, and converted with convert. Single-file XBLA/XBLIG STFS packages are accepted by -l, -t, -x, --unpack, -V, checksum and --json; the STFS file table is read directly (they are not sector images, so compress, decompress, convert, rewrite, split and the raw redump modes refuse them with an "extract first" message). Sector-only verbs (-i, --ls, -V, --filetime, --sector-layout, --ranges, --repair, …) reject a .zar with a clean error naming the archive verbs instead of probing compressed bytes. In-place write verbs (-r, --repair, --copy-in, --set-filetime) and split refuse a GOD source and ask for decompress first.

Flag Description
-c <dir> [name] Create an ISO from the contents of <dir>. Optional name overrides the output filename (may include a path). Default output is <dir leaf>.iso in the current directory; a current-directory source (-c . / -c ..) defaults to the source's parent instead (mirroring -c <leaf> from there). Repeatable for batch creation. Excludes -X patterns; with -s, $SystemUpdate is skipped automatically.
--pack <input> [name] Pack a directory into an ISO (1:1 mapping; name defaults to the directory name and may include a path), or repack an existing ISO in place (rewrite mode, source renamed to .old). Translates internally to create or rewrite mode. Already-optimized images are skipped.
-x Extract (explicit; the default mode).
--unpack <file> [dest] Unpack the whole image to dest, or to a directory named after the ISO (minus .iso) in the current directory when omitted. Detects the optimized layout automatically; supports --skip-sectors, --skip-existing (resume) and --jobs 1..64 (copy independent files in parallel; output is byte-identical). A single-file XBLA/XBLIG STFS package is unpacked through its file table.
-l List the top-level entries of each ISO (non-recursive). A .zar or an XBLA/XBLIG STFS package lists its archive/package tree instead.
-t Tree — recursive listing with full paths, sizes, and totals. .zar and XBLA/XBLIG STFS packages are supported.
-i <file> [path] Info — volume descriptor metadata (incl. detected disc format: RAW / GLOBAL (XGD2) / XGD3 / XGD2 Hybrid / XGD1) plus per-entry details (sector, size, attributes, left/right child offsets). path defaults to /.
--ls <file> [path] List directory — entry names of a directory (default /), without recursion. Prints one name per line; /path: empty directory when empty. Mirrors ls on the image.
--xex-info <file> <path> XEX info — parse and display the Xbox 360 XEX2 executable header of a .xex file inside the image (module flags, entry point, image base/size, region, media types, media/title ID, version, disc, encryption/compression). XDBF/XSRC title name, publisher, developer, genre and description are printed when present.
--xbe-info <file> <path> XBE info — parse and display the original-Xbox XBEH header + certificate of a .xbe file inside the image (base, entry point, sections, title ID/name, media, region, ratings, disc, version). --json also reports hasLogoBitmap / hasTitleImage / hasSaveImage.
--xbe-image <file> <path> --type logo|title|save -o <out.png|out.dds> XBE image — extract the Microsoft logo bitmap, the $$XTIMAGE title image or the $$XSIMAGE save image as PNG or DDS. DXT1/3/5, BGR24/BGRA32, XPR0 and the 54-byte title-image header are decoded; an unsupported payload is a clean error.
--md5 <file> [path] Compute MD5 hashes of files inside the image. No path → hash every file in the image; directory → recursive; file → single hash. Output: lowercase hex + two spaces + path.
--sha256 <file> [path] Compute SHA-256 hashes of files inside the image (same semantics as --md5).
-V <file1.xiso> ... Audit — deep integrity check of one or more images: header, tree walk, sector bounds, cycle detection, reserved attribute bits 0x48 masked, 0x0000 sentinel. The optimized tag is reported (Optimized: yes/no) but is not required, so raw/unconverted dumps pass; run --is-optimized for a strict tag-only check. An XBLA/XBLIG STFS package is audited through its SHA-1 hash tree instead (every data block, the level-0/1/2 tables, the top hash and the header hash; package signatures are not checked). Prints Files checked / Dirs checked / Optimized / `Result: PASS
--repair <file> Repair — fix the audit's safely-patchable issues in place: reserved attribute bits, missing optimized tag, separators in filenames. Writes <file>.old backup first unless --no-backup. Prints Fixed: / `Result: PASS
--dry-run With --repair, preview the fixes without changing anything (exit mirrors the audit: 1 when fixes would apply). Rejected without --repair.
--salvage <file> Salvage — rebuild a readable image from a corrupt one: carry every entry reachable without tripping a truncation/structural gate into <file> named after the game plus .salvaged.iso (game.2.cci → game.salvaged.iso; CISO/CCI input allowed; source never modified). Prints Carried: / Dropped: / `Result: PASS
--repair-out <path> With --salvage, write the rebuilt image to <path> instead of the default (existing files follow the -y/-n convention). Rejected without --salvage.
--batch <dir> Process every supported image in <dir> instead of explicit filenames. On the main modes it scans .iso files and works with extract, list, tree, rewrite (-r), and audit (-V); on the container verbs it scans the verb's own inputs (compress: .iso/.xiso; decompress: .cso/.cci; convert --format zar: unsplit .iso/.xiso; convert --format iso: .zar; split: unsplit .iso/.xiso). Split sets are collapsed to their first part (.1.cso, .1.cci, .1.iso). Sorted for deterministic order.
--batch-recursive With --batch, search subdirectories recursively. Rejected without --batch.
--output-name <template> With a batch container verb, name outputs from {name} (source stem with a .1 split marker and the container extension stripped), {ext} (source extension), and {format} (output format). Example: --output-name "{name}.xiso.{format}". Relative templates resolve against each source's directory; a template without an extension gets the format's extension. Rejected without --batch.
--copy-out <iso> <path> <dest> Copy a single file or an entire directory out of an ISO to <dest>. Supports --skip-existing (resume) and --continue-on-error.
--copy-in <iso> <host> <path> Copy a host file into an ISO, modifying it in place: replaces <path> when it exists, adds it as a new file otherwise. A host directory is rejected fast (InvalidDataException, nothing written). Writes an <iso>.old backup first unless --no-backup. See CopyIn.
--no-backup With --copy-in or --repair, skip the <iso>.old backup (rejected without either).
-r Rewrite each ISO as an optimized ISO (see Optimized-tag detection). Already-optimized images are skipped. Output is byte-identical to extract-xiso -r (SHA-256 verified on real dumps): dirent attributes are re-encoded with the DIR/ARC defaults; pass --preserve-attrs to keep the source bits instead.
validate <src> <out> Standalone validation command — must be the first token. Both sides accept ISO, CISO/CCI (single or split), split plain-ISO sets, GOD and .zar. See Validation.
--video Redump: extract video partition (L0 head + L1 tail) via XisoRedump.TryExtractVideo + XgdTables wave tables; writes *.video.iso. Fails gracefully when videoType==-1. See Archival.
--random Redump: extract random filler/padding (XisoOperations.ExtractFiller via GetXisoRanges/MergeRanges); writes *.filler. See Archival.
--seed Redump: extract XGD1 RNG seed (brute-force XboxPrng, XGD1 only); writes *.seed. See Archival.
--wipe Redump: zero filler gaps (XisoOperations.WipeFiller → ProcessWipe); writes *.wiped.xiso. Part of --best. See Archival.
--trim Redump: truncate after last file extent (ranges[^1].End+1 * SectorSize); writes *.trim.xiso. See Archival.
--petrify Redump: skeleton — XISO with file extents zeroed + SHA-1 per file (XisoSkeleton.Petrify, CollectFileEntries sorted); writes skeleton + *.hash. See Archival.
--update Redump: extract system update su20076000_00000000 from XGD3 video L1 tail (XisoRedump.TryExtractUpdate, FindUpdateOffset ABCDABCD); warns on XGD1/2. See Archival.
--zar Create ZArchive/zstd (XisoZarchive.CreateZar → ZArchiveSharp.ZArchiveWriter, L6 blocks + raw fallback; standalone --zar -o <out.zar> <iso> or Redump-batch zar of the XISO component). Load the result directly in Xenia canary. See Archival.
--jobs <n> Collection and extraction parallelism (1..64, default 1). With a lone --zar over several inputs, pack up to <n> archives in parallel. On a batch container verb (compress, decompress, convert, split), run up to <n> conversions in parallel. On a single-file CISO or CCI compress, compress sectors with <n> workers. Multi-image checksum, hash, -V/audit and extract/list/tree/rewrite process up to <n> images at once; output (including JSON arrays) is byte-identical to --jobs 1. In extract (-x) and --unpack modes, copy independent files with up to <n> workers.
--symlink-mode follow|skip|reject Create-time link policy for -c, --pack, build-image and apply-skeleton. follow (default) packs file symlinks as their target content and skips directory reparse points; skip omits file and directory links and logs them; reject fails with the offending link path before writing. Cyclic directory links always terminate.
--policy <p> --zar overwrite handling without prompting: skip | overwrite | auto-rename.
--zar-level <1..22> zstd compression level for --zar, --compress and convert --format zar; the default 6 stays byte-identical to the historical output. The 64 KiB ZAR block size is format-defined and not configurable.
--deterministic Alias for --file-time 0; accepted for create (-c), --pack, rewrite (-r) and build-image, so repeated packs are byte-identical.
--strict-names Fail before writing when a path component exceeds the Xbox 42-character limit or is outside Latin-1. The default warns and packs; +, !, spaces and Latin-1 characters are valid.
--all Alias: --random --seed --trim --update --video --wipe (→ --xiso as batch). Mirrors XboxKit -a.
--best Alias: --trim --wipe (XISO). Mirrors XboxKit -b.
--compress Alias: --petrify --update --video --zar. Mirrors XboxKit -c. Also see xdvdfs compress.
--security-sectors <file> Rebuild-only override of the security sector ranges (start-end lines, 4096 sectors each, 4095 validated, sorted int[]). Alias: --sectors. Rejected outside the rebuild verb.
rebuild <xiso|game.zar> [video.iso] [filler|seed] [su…] -o <redump.iso> Rebuild Redump ISO (XisoRedump.RebuildRedump): L0+l0Padding+game partition scan (filler/PRNG + security-sector zero-skip) + l1Padding+L1 (optionally l1Trimmed+updateFS+lastSector). <xiso> accepts a .zar sidecar (single embedded XISO verbatim, else tree repacked). Positional alias XISOSharp <input.xiso> [files...] also accepted. See Archival.
build-image [sourceDir] [output.iso] -m "host:image" [-f <toml>] [-O output] [-D|--dry-run] [--file-time <value>] xdvdfs parity: ordered wax remapping (RemapFilesystem, WaxGlob */**/?/[]/{a,b} + {0} whole + {n} groups, !negation first-wins, suffix re-add), xdvdfs.toml [map_rules], --dry-run via DryRunRemap → CreateFromRemapTree (IsRemap skips CWD). In -m rules the separator is the first unescaped : — write \: for a literal colon, \\ for a backslash. See xdvdfs Compat.
image-spec from -O <out> -m "host:image" ... [specPath] xdvdfs parity: TOML generation (GenerateSpecText preserve-order [metadata] output + [map_rules]), stdout when specPath omitted. See xdvdfs Compat.
compress|cso|cci <src> [out] [--format cso|cci] [--ciso-level 0..9] [--ciso-version 1|2|auto] [--ciso-split bytes] [--cci-level 0..12] [--cci-split bytes] [--jobs <n>] [--batch <dir>] CISO/CCI compress. CISO (CisoWriter.CompressToCso): v2 (default) LZ4 sectors with fixed align 2, byte-identical to modern xdvdfs compress (pure-managed lz4_flex port); v1 BCL DEFLATE 0x80000000 with dynamic align 0/1/2; threshold +12. --jobs 1..64 compresses CISO sectors on a bounded worker pool with byte-identical output. CCI (XisoCci.CompressToCci, CCISharp 1.1): fast LZ4 levels 1..9 or managed LZ4-HC levels 10..12, spec-valid and interoperable (HC byte parity is best-effort); --jobs 1..64 parallelizes CCI sectors with byte-identical output. Use on sourceDir, image.iso, a split ISO/CISO/CCI source, or a GOD header/.data folder (decompressed to a temporary ISO first). CISO splits at 0xffbf6000 (~4 GiB) into .1.cso/.2.cso parts; CCI into .1.cci/.2.cci. --*-split 0 writes a single file. With --batch, converts every .iso/.xiso in <dir>. See Compression.
decompress|uncso|decso|uncci <cso|cci|god> [out.iso] [--batch <dir>] CISO/CCI/GOD decompress: compressed containers are detected by extension/magic; CisoReader.DecompressToIso handles CISO v1/v2, XisoCci.DecompressToIso handles CCI, and a GOD header/.data folder is streamed to ISO (named after the header title when the output is omitted). Single files and split .N.cso/.N.cci parts are supported. With --batch, converts every .cso/.cci in <dir>.
checksum [--silent] <image> [images...] / --checksum <image> [--silent] SHA3-256 image checksum (XisoChecksum.ComputeImageChecksum, SortedDictionary Ordinal /path UTF-8 + streamed data, xdvdfs compat). .cso/.1.cso, .cci/.1.cci, split .1.iso and GOD header/.data inputs are auto-detected and read through the decompressed/concatenated view - result identical to the source ISO. .zar inputs use ComputeZarChecksum (same tree hash) - also identical. XBLA/XBLIG STFS packages use ComputeStfsChecksum, the same sorted-path SHA3-256 tree hash, so equivalent ISO/ZAR/STFS trees compare equal. Prints hex tab path (--silent = hex only). Also flag form --checksum supports multiple ISOs (--silent requires --checksum in flag form). See xdvdfs Compat.
hash <image> [images...] [--json] Full-image hashes (XisoImageHash.Compute): CRC32, MD5, SHA-1, SHA-256 and SHA3-256 in one streaming pass over the decompressed view, so ISO, split ISO, CISO, CCI and GOD agree. --json emits a hashes array.
verify-hashes <image> <hash-file> [--ignore-extra] [--json] Verify a .hash sidecar produced by --petrify or file-hashes. Digests are detected by line length: MD5 (32), SHA-1 (40) or SHA-256 (64); works for ISO, split ISO, CISO, CCI, GOD, STFS and ZAR. Missing/mismatched files fail; extra image files are reported and can be ignored with --ignore-extra.
verify-dat <dat> <image> [images...] [--json] Verify Redump DAT entries (XisoDat.Verify): parses a Redump-style XML DAT (game/rom size + MD5/SHA-1/CRC32), hashes each image once, and reports VERIFIED, AMBIGUOUS, NOT IN DAT plus DAT entries not matched by any supplied image. Exit 0 when every supplied image matches exactly one entry. No DAT source is bundled.
file-hashes <image> [-o <file>] [--algorithm sha1|sha256|md5] [--json] Generate a per-file sidecar for any supported container through XisoReader.ComputeFileHashSidecar. The default output is <image stem>.hash in the SHA-1 format verify-hashes consumes; -o - writes the lines to stdout.
disc-info <image> [--json] [--sectors <file>] [--skip-sectors <n>] Redump/XGD layout inspector (XisoDiscInfo.Read): XGD generation/subtype and wave, video L0/L1 and game-partition byte/sector ranges, PFI presence and layer break, embedded security-sector ranges (falling back to sectors.txt), known-Redump-size match, and consistency warnings. Containers report the game-partition view and mark video/PFI fields unavailable.
apply-skeleton <skeleton.xiso> <source-dir> -o <out.iso> [--hash <file>] [--strict-names] Skeleton overlay (XisoSkeleton.Apply): the inverse of --petrify. Copies the skeleton's filesystem/system sectors, places each source file at its recorded extent, and verifies the optional .hash while writing. Missing/extra files, size mismatches and hash mismatches are named errors.
xex-image <image> <path> --type thumbnail -o <out.png> Export the XDBF thumbnail (0x8000 entry) from a default.xex; the loose-file form (xex-image game.xex ...) is accepted. Absent or non-PNG payloads are clean errors.
title-info <image> [--json] Title metadata: finds the root default.xbe, default.xex or default_mp.xbe and reports title name, title ID, region, disc number and version. Xbox 360 titles additionally report publisher, developer, genre, description and thumbnail presence from the plaintext XDBF/XSRC resources. A GOD header or its .data folder is also accepted; it reports the XContent title name, title ID, disc number and disc count and merges the embedded default.xex publisher/developer/genre/description/thumbnail. Single-file XBLA/XBLIG STFS packages are accepted too (StfsSharp.StfsHeader, content types 0x000D0000 / 0x00000002; Community Game 0x02000000 is treated as XBLIG) and merge default.xex metadata the same way.
split [--size <bytes|half>] [--output <base>] <image> [images...] [--batch <dir>] Split a plain ISO into sector-aligned <base>.1.iso, <base>.2.iso, … parts (XisoSplitter.Split, TODO #17 / xdvdfs #97 — the plain-ISO counterpart to CSO --ciso-split). --size accepts bytes with K/M/G suffixes or half/halves; default 0xFF000000 (4 GiB − 16 MiB, conservative FATX cap); an explicit larger size warns. Base defaults to the input stem. Existing parts are refused; partial parts are removed on failure/cancel. With --batch, splits every unsplit .iso/.xiso in <dir>.
join|joinsplit [--output <file>] <first.1.iso> [...] Reassemble split parts (XisoSplitter.Join). Output defaults to the part stem + .iso and must not exist; the result is validated as an XISO afterwards.
convert <src.zar|src.iso|god> <out.iso|out.zar|out.cci|out.cso> [-y|-n] [--batch <dir> --format iso|zar] Convert ZArchive to ISO (XisoZarchive.ConvertZarToIso: extract to a temp directory then XisoWriter.PackFromDirectory), ISO to ZArchive (CreateZar), or a GOD container to ISO/CCI/CISO (streamed through the decompressed view). Existing outputs follow -y/-n. With --batch, converts every unsplit .iso/.xiso to .zar (--format zar, default) or every .zar to .iso (--format iso).

The redump modes read and write absolute sectors through a raw file stream, so they accept only plain .iso/.xiso images. A .cso/.cci, a split-ISO part, a .zar, a GOD container or an XBLA/XBLIG STFS package is refused up front with a "decompress/convert/join/extract first" error (use decompress, convert, join or -x).

Options

Flag Description
-d <directory> Extract mode: output directory (created if missing). Rewrite mode: directory for the rewritten ISO. Ignored by list/tree. Tolerant of batch-script artifacts: trailing separators, UNC paths, spaces — see Destination directory edge cases.
-D Rewrite mode: delete the .old source file after a successful rewrite. Also build-image --dry-run alias (-D/--dry-run/--dryrun preview host→image pairs without writing).
-m In create or rewrite mode, disable automatic .xbe media enable patching (not recommended).
-o <filename> Rewrite/rebuild/compress output filename (default: original name with .iso/.cso extension). Relative names resolve against -d; rooted (absolute) paths are used as-is. For rebuild must be -o <redump.iso>; for compress optional positional.
-q Quiet — suppress all non-error output.
-Q Silent — suppress all output, including errors.
-v, --version Print the version banner (first line unchanged) followed by XISOSharp, CCISharp, ZArchiveSharp, runtime, OS, architecture and MinVer commit.
--json Machine-readable output for read-only modes: -i, -l, -t, --checksum/checksum, --sector-layout, --ranges, --filetime, --xex-info, --xbe-info, validate, and -v/--version. JSON is written to stdout; human logs move to stderr. See JSON output.
-s Skip $SystemUpdate entries. On create this is equivalent to -X "**/$SystemUpdate/**"; on extract/rewrite it filters $SystemUpdate paths while reading.
-X <glob_pattern> Create mode only. Exclude files/directories matching the glob pattern. Repeatable. See Exclude patterns. WaxGlob engine also supports {0}/{n} captures for build-image.
-y, --yes Always overwrite output files without prompting (rebuild, rewrite -o, compress, decompress, redump batch outputs).
-n, --no Never overwrite: refuse when an output file exists (prints [ERROR] File already exists, skips the operation). Cannot be combined with -y.
--skip-sectors N Treat the image as if the XISO filesystem starts N sectors (2048 bytes each) into the file — for Redump images with a video partition. Valid in extract, list, tree, rewrite (-r), --unpack, --filetime, --set-filetime, and --is-optimized modes. Rejected with -c and with -i, --ls, --xex-info, --xbe-info, --md5/--sha256, --copy-out, --copy-in, -V, validate/--validate*, redump verbs, checksum, --sector-layout, and --ranges; also rejected for XBLA/XBLIG STFS packages. See Redump & Disc Layouts.
--prepend-sectors N Write the output image with N empty sectors before the XISO filesystem, reserving room for a video partition. Valid in create (-c) and rewrite (-r) modes. See Redump & Disc Layouts.
--layout <file> Explicit sector-layout packing. Create (-c), --pack <dir> and build-image place files/directories at the sectors named by a --sector-layout --json file or a compact path=sector text spec (total-sectors=N optional, 0x hex allowed, #/; comments). Unlisted entries are allocated first-fit around the fixed extents. Overlaps, extents in the reserved system area, extents outside total-sectors, and extents smaller than the source entry needs fail before writing. JSON layouts may name files the source tree lacks (their extents are reserved); the text form rejects unknown paths. See XisoWriter API.
--preserve-attrs Rewrite (-r) mode: re-encode the source dirent attribute bits (RO/HID/SYS/NOR) into the output instead of the extract-xiso parity default (DIR/ARC defaults, dir=0x10/file=0x20). Default off so rewritten images stay byte-identical to extract-xiso -r.
--file-time <value> Fixed FILETIME for the volume descriptor on create (-c), --pack, and build-image (values: ISO-8601, decimal raw, 0x hex, 'now', '0'). '0' writes the xdvdfs deterministic timestamp so identical input produces byte-identical output. See XisoWriter API.
--filetime <image> Show the FILETIME volume-descriptor field (ISO-8601 + raw u64; 0 = 1601-01-01, xdvdfs compatible). See FILETIME.
--set-filetime <image> <value> Set the FILETIME field (values: ISO-8601, decimal raw, 0x hex, 'now', or '0'). Cannot be combined with other modes. See FILETIME.
--sector-layout <image> Sector layout — full on-disk map (XisoReader.GetSectorLayout): volume summary (format, root dir sector/size, total sectors), per-file extents (path, start sector, sector count, bytes), and used/free sector ranges (inclusive spans). Offset-0 only (--skip-sectors rejected).
--ranges <image> Sector ranges (XisoRanges.GetXisoRanges): system (bone) vs file sector ranges as inclusive start-end spans, with counts. Reads plain ISO, split ISO, CISO and CCI through the container-aware view. Offset-0 only (--skip-sectors rejected).
--is-optimized <image> Print <iso>: optimized or <iso>: not optimized (XisoReader.IsOptimizedImage tag probe at offset 31337); supports --skip-sectors. Always exits 0 on a readable image.
--skip-existing In extract, --unpack, and --copy-out modes, skip files already on disk with matching sizes (logged as skip: <path>) instead of overwriting them. Re-run an interrupted unpack to resume it; pairs with --batch. On a batch container verb (compress, decompress, convert, split), skip a source whose output already exists (for split, every expected part must exist; a partial set is resumed). See Resume interrupted unpacks.
--continue-on-error In extract, --unpack, and --copy-out modes, log per-file failures (Error: Failed to extract ...) and continue with the next entry instead of aborting. An uncreatable directory skips its subtree. The run still ends with a Failed to unpack image summary and a non-zero exit code. On a batch container verb, keep converting after a failed file, remove any partial output, and return exit code 1 after the summary. XBLA/XBLIG STFS extraction is all-or-nothing and rejects this flag. See Extraction robustness.
--name-policy reject|sanitize|skip In extract (-x) and --unpack modes, choose how host-unsafe entry names are handled: reject (default; named error and abort), sanitize (replace unsafe characters with _, add ~N on collisions), or skip (omit the entry and a skipped directory's subtree). Applies to ISO/split ISO/CISO/CCI/GOD, ZAR and XBLA/XBLIG STFS extraction. See Hostile entry names.
--delete-source On a batch container verb (compress, decompress, convert, split), delete each source after its conversion succeeds. Requires -y/--yes; rejected with -n/--no. A split set deletes every part. Failed conversions keep their source, and the batch summary reports the deleted count.
--ciso-level 0..9 CISO compression level (compress/cso, default 9). v1: maps to CompressionLevel for BCL DEFLATE (0 NoCompression, 1..3 Fastest, 4..6 Optimal, 7..9 SmallestSize). v2: 0 = store all plain, 1..9 = LZ4 acceleration 10 - level (level 9 byte-identical to xdvdfs).
--ciso-version 1|2|auto CISO payload codec (compress/cso). Default 2 (LZ4, align 2 — modern xdvdfs parity); 1 = classic DEFLATE.
--ciso-split <bytes> Split point for .1.cso/.2.cso… output (compress/cso). Default 0xffbf6000 (~4 GiB, xdvdfs SplitOutput); 0 = single .cso.
--format cso|cci Output container for compress (default cso; cci selects CCISharp).
--cci-level 0..12 CCI compression level (compress/cci): 0 = store every sector raw; 1..9 map to the fast LZ4 encoder acceleration (10 - level); 10..12 select the managed LZ4-HC encoder (12 = highest effort).
--cci-split <bytes> CCI split point (compress/cci). Default 0xffbf6000 (~4 GiB) into .1.cci/.2.cci; 0 = single .cci.
-p (Hidden) Print usage and exit 1.

Overwrite behavior

File-producing verbs (rebuild, rewrite with -o, compress, decompress, and the redump batch flags --video/--random/--seed/--wipe/--trim/--petrify/--update/--zar) check their output path before writing (XboxKit/Helpers.cs::ConfirmOverwrite parity): an existing output prints [WARNING] File already exists and prompts Would you like to overwrite? (Y/N) — only Y/YES (case-insensitive) proceeds. -y/--yes skips the prompt (always overwrites); -n/--no refuses without prompting (the operation is skipped; batch runs continue with the remaining outputs but exit 1). Per-file extract/unpack outputs are not gated. For compress with split output the first part (<base>.1.cso) is the probe path; rewrite checks -o before moving the input aside to <name>.old.

Input==output safety guard

Separately from the prompt above, an output that points back at one of its inputs is refused outright (exit 1, before any prompt, move, or write) — it can never be what you meant:

  • rewrite -o equal to the input (omit -o to rewrite in place), or to the <name>.old backup the rewrite itself needs;
  • any other single-input -o (wipe/trim/compress/decompress/…) equal to the input;
  • rebuild -o equal to any component (xiso, video, filler/seed) or the sectors file;
  • compress whose split output parts (.1.cso/.2.cso…) would overwrite the source.

The only same-path write allowed is the one with explicit in-place semantics and no -o: TrimXiso(input, input) (safe SetLength truncation), and rewrite without -o (which works via the .old rename). Diagnostics name both sides, e.g. Error: rewrite output game.iso is the same file as the input; omit -o to rewrite in place.

Resume interrupted unpacks

An unpack killed mid-run (Ctrl+C, power loss, disk full) leaves a partial destination. Re-run the same command with --skip-existing to resume: every file already on disk with the same byte size is left untouched and logged as skip: <path>; missing files — and short files from torn writes — are written normally.

XISOSharp --unpack game.iso ./out                 # interrupted halfway
XISOSharp --skip-existing --unpack game.iso ./out # resumes: skips done files
XISOSharp --skip-existing --batch ./isos -d ./out # bulk runs resume per image

Notes:

  • Size is the identity signal: XISO stores no per-file timestamps, so a same-size file is assumed to be a complete earlier write (even if its content differs — the flag means "don't touch what's there").
  • Cancellation is honored per entry, so Ctrl+C stops promptly; the working directory never changes.
  • --skip-existing is rejected outside extract / --unpack / --copy-out (exit 1).

Parallel extraction

--jobs <n> (1..64, default 1) on extract (-x) and --unpack copies independent files with up to <n> workers. The directory tree is still walked and created on one thread; once the walk finishes, the queued files are copied concurrently. Per-file FileAdded progress and the extracting/skip: log lines are emitted in traversal order, matching a sequential run (parallel mode logs one completion line per file instead of per-chunk percentage updates). Output is byte-identical to --jobs 1.

XISOSharp -x --jobs 4 -d ./out game.iso
XISOSharp --unpack --jobs 8 game.iso ./out

Plain ISO images are read positionally (no shared seek position). CISO/CCI, GOD, split ISO and in-memory sources serialize their reads behind a lock, so they are safe but see less speed-up; destination filesystem calls are serialized as well, which keeps non-thread-safe stores (for example MemoryFilesystem) correct. Byte-level FileProgress events may interleave between files, while per-file FileAdded events stay ordered. A failure still surfaces as the named ExtractFileException (or the --continue-on-error summary), and --jobs is rejected for ZAR/STFS unpacking and outside extract/--unpack. Without --continue-on-error, the first failure is thrown after the queued copies finish, so a parallel run may leave files extracted that a sequential run would not have reached.

Extraction robustness

A damaged image or a hostile destination no longer dies with a bare OS error (upstream xdvdfs #187: the web unpacker could only report Failed to create file X). Every per-file failure throws ExtractFileException, which names the entry, its sector, and expected vs actual bytes, with the OS error as the inner exception:

XISOSharp -x -d ./out game.iso
# Error: Failed to extract "./out/videos/intro.wmv" (sector 1234, 20000 bytes) -> "intro.wmv": could not create output file: ...

Extracted files are integrity-checked two ways: an entry whose data range lies past the end of the image is refused before its destination is created, and the bytes on disk are re-statted after the copy — a short image (truncated download, torn file, entry pointing past the end) fails the file with ErrFileTruncated instead of leaving a short file behind. (The old code merely warned — and spun forever on a 0-byte read at end of image.)

With --continue-on-error, a failed file is logged and skipped while the rest of the image still extracts; an uncreatable directory skips its whole subtree. The run still ends with a summary naming every failure, and a non-zero exit:

XISOSharp --continue-on-error --unpack game.iso ./out
# Error: Failed to extract ... (logged per file as it happens)
# Failed to unpack image "game.iso": 2 file(s) failed:
#   Failed to extract ...

Notes:

  • Structural corruption (an unreadable directory table) is contained by the traversal hardening: under --continue-on-error the bad subtree is skipped and recorded like any other failure; without it, the named TOC error aborts.
  • Failed files are excluded from the file/byte totals and FileAdded progress.
  • --continue-on-error is rejected outside extract / --unpack / --copy-out (exit 1), and pairs with --skip-existing and --batch.

Hostile entry names

Image names are Latin-1 byte strings, so a hostile or damaged image can contain path separators, drive-relative colons, trailing dots/spaces or DOS device names (CON, NUL, COM1…). By default extraction rejects such an entry with a named error and aborts the walk. --name-policy lets a recovery run choose a different outcome:

# Rename unsafe entries to host-safe names; collisions get ~1, ~2, ...
XISOSharp --name-policy sanitize --unpack game.iso ./out

# Omit unsafe files (and a skipped directory's whole subtree), extract the rest
XISOSharp --name-policy skip --unpack game.iso ./out

sanitize replaces unsafe characters with _ and disambiguates names that collide in the same directory (for example a:b.txt and a?b.txt become a_b.txt and a_b~1.txt). Every rename is logged to stderr. skip logs skip: <path> (unsafe entry name) and is not counted as a failure. The policy applies to ISO, split ISO, CISO, CCI, GOD, ZAR and XBLA/XBLIG STFS extraction; an explicit --copy-out destination is caller-chosen and is unaffected. The flag is rejected outside extract/--unpack (exit 1).

Destination directory edge cases (-d)

Batch scripts build -d values by concatenation, so the usual artifacts are tolerated (upstream #61):

  • Trailing separators (-d .\new\game\, doubled, or mixed /\) are stripped — including the filesystem-root case (-d C:\ stays C:\, never the drive-relative C: that Path.Combine would mis-resolve).
  • UNC destinations (-d \\server\share\dir), \\?\-prefixed paths, and directories with spaces all work; an unreachable host fails fast with an IOException instead of hanging.
  • An empty -d (-d "%UNSET_VAR%") is rejected with Output path must not be empty (exit 1).
  • A -d pointing at an existing file fails with an IOException; the process working directory is unchanged either way.

Misplaced flags (upstream #61)

extract-xiso game.iso -d ./new/ never worked upstream: getopt stops at the first filename, so -d was opened as an image (open error: -d). This CLI keeps the flags-first contract, but a known flag spelling in a filename slot now fails fast with a named error instead of a bogus open attempt:

XISOSharp game.iso -d ./new/
# Error: -d must come before ISO filenames (e.g. -x -d <value> game.iso); a flag after the first filename is read as a filename

The check is skipped when the token exists on disk, so a file literally named like a flag keeps working.

Exclude patterns

-X accepts shell-style glob patterns matched against paths relative to the source root, using / as the separator. Matching is case-insensitive.

Pattern Matches
*.tmp .tmp files at the root only (no **/ prefix → anchored to root)
**/*.tmp .tmp files at any depth
**/node_modules/** any node_modules directory (and everything below it)
screenshots/** the root-level screenshots directory and its contents
**/$SystemUpdate/** $SystemUpdate directories at any depth (what -s implies)

Supported syntax: * (within one segment), ? (one character), ** (zero or more segments as a complete segment), [abc]/[a-z]/[!abc] character classes, and \x escapes. A trailing / is equivalent to /**.

For build-image, the same engine (WaxGlob) additionally supports capture groups {0} (whole match) and {1..n} (per */** segment) and ordered evaluation with ! negation — see xdvdfs Compat — Build-Image.

Validation flags

These integrate with -r or the standalone validate command — see Validation for the full picture. They require -r (rewrite) or validate mode (mismatch exits 2); the flavor flags imply --validate.

Flag Description
--validate After a rewrite, compare the source and output file trees (counts, paths, sizes).
--validate-checksums Also verify SHA-256 checksums per file (slower). Implies --validate.
--validate-strict Fail with exit code 2 on any mismatch (retained for parity; mismatches now exit 2 with or without it). Implies --validate.
--validate-report <file> Write the validation result as a JSON report. Implies --validate.

Mode combinations and restrictions

Enforced at parse time; violations print an error and exit 1:

Combination Result
--skip-sectors with -c Error
--prepend-sectors without -c or -r Error
--layout without -c <dir>, --pack <dir> or build-image (e.g. with -r, -l, --pack <iso>) Error
--preserve-attrs without -r Error
--skip-sectors/--prepend-sectors with -i, --ls, --xex-info, --xbe-info, hash, --copy-out, --copy-in, -V, validate/--validate*, redump verbs, checksum, --sector-layout, or --ranges Error
--validate/--validate-checksums/--validate-strict/--validate-report without -r or validate Error
-X without -c Error
--skip-existing without extract/--unpack/--copy-out (e.g. with -l, -t, -r, -c, redump verbs) or a batch container verb (compress, decompress, convert, split) Error
--continue-on-error without extract/--unpack/--copy-out or a batch container verb Error
--name-policy without extract (-x) or --unpack Error
--jobs outside a lone --zar, a batch container verb, a single-file CISO/CCI compress, extract/--unpack, multi-image checksum/hash/-V/-l/-t/-r Error
--symlink-mode without -c, --pack <dir>, build-image or apply-skeleton Error
--output-name without a batch container verb Error
--batch without extract/list/tree/rewrite/audit or a container verb (compress, decompress, convert, split) (e.g. with --copy-out, --copy-in, validate, redump, checksum, --filetime, --sector-layout, --ranges, --is-optimized) Error
--batch-recursive without --batch Error
--no-backup without --copy-in or --repair Error
--dry-run without --repair Error
--repair-out without --salvage Error
--silent without --checksum (flag form) Error
--filetime/--set-filetime with redump or --batch Error
-c with extra positional arguments Usage error
-y with -n Error ([ERROR] Cannot use both --no (-n) and --yes (-y))
No positional arguments in a non-create/non-verb mode Usage error
--ciso-* / --cci-* / --format without compress/cso/cci Error (verb-only flags, parsed by RunCompressMode; --ciso-* and --cci-* are also rejected for the other format)
--security-sectors/--sectors outside the rebuild verb Error (only supported by the rebuild verb)

Flags that take arguments (-c, -d, -o, -X, --skip-sectors, --prepend-sectors, --validate-report, --security-sectors/--sectors, --ciso-level, --ciso-version, --ciso-split, --jobs, --policy, --repair-out, -f, -m/--map, -O/--output) consume the next token. For -c, the optional name is consumed only when the next token does not start with -.

JSON output

--json turns every read-only verb into a stable, source-generated JSON document (schemaVersion: 1). JSON owns stdout; banners, progress, warnings and errors stay on stderr, so pipes and ConvertFrom-Json are safe.

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 --json
Command Top-level shape
info { schemaVersion, command, source, path, volume, entries[] }
list / tree { schemaVersion, command, images[{ source, fileCount, totalBytes, entries[] }] }
checksum { schemaVersion, command, checksums[{ path, algorithm, hash }] }
sector-layout { schemaVersion, command, source, volume, fileCount, dirCount, entries[], usedRanges[], freeRanges[] }
ranges { schemaVersion, command, source, system[{ startSector, sectorCount }], files[...] }
filetime { schemaVersion, command, source, iso8601, raw, hex }
xex-info / xbe-info { schemaVersion, command, source, path, ...parsed fields }; xex-info adds optional titleName / publisher / developer / genre / description / hasThumbnail when XDBF is present, and xbe-info adds hasLogoBitmap / hasTitleImage / hasSaveImage.
title-info GOD: { schemaVersion, command, source, kind: "god", headerPath, titleName, titleId, titleIdHex, discNumber, discCount, xexPath?, publisher?, developer?, genre?, description?, hasThumbnail? }; XBLA/XBLIG: { schemaVersion, command, source, kind: "xbla"|"xblig", packagePath, titleName, titleId, titleIdHex, discNumber, discCount, contentType, xexPath?, publisher?, developer?, genre?, description?, hasThumbnail? }; XBE: { schemaVersion, command, source, kind: "xbe", xbePath, titleName, titleId, titleIdHex, gameRegion, gameRegionName, diskNumber, version }; XEX: { schemaVersion, command, source, kind: "xex", xbePath, xexPath, titleName, titleId, titleIdHex, gameRegion, gameRegionName, diskNumber, version, discCount, publisher?, developer?, genre?, description?, hasThumbnail? }
disc-info { schemaVersion, command, source, format, isContainer, fileLength, totalSectors, volume, discFormat, xgdType, redumpTypeIndex?, redumpSizeMatch, redumpTypeName?, videoTypeIndex?, videoTypeName?, wave?, videoL0?, videoL1?, gamePartition?, pfi?, securitySectorsSource?, securitySectors[], warnings[] }
file-hashes { schemaVersion, command, source, output?, algorithm, fileCount, totalBytes, entries[{ path, size, algorithm, hash }] }
verify-hashes Adds algorithm to each entry (md5/sha1/sha256) alongside expectedSha1/actualSha1 (historical field names; values are the detected algorithm's hex digest).
verify-dat { schemaVersion, command, dat, passed, verified, missing, ambiguous, notInDat, images, results[{ image, status, size, md5, sha1, crc, matches[] }], missingRoms[] }; DAT entries are { game, name, size, md5, sha1, crc }.
validate { schemaVersion, command, source, output, checksums, passed, sourceSummary, outputSummary, issues[] }
-v / --version { schemaVersion, command, xisoSharp, cciSharp, zArchiveSharp, runtime, os, architecture, commit }
  • Property names are camelCase; nulls are omitted.
  • list and tree always wrap their results in an images array, even for a single input, so multi-image runs stay one JSON document.
  • --json is rejected for mutating/streaming modes (extract, rewrite, create, compress/decompress, redump, etc.); use the text output there.
  • Serialization uses JsonOutputContext (System.Text.Json source generation), so the trimmed single-file CLI keeps working with no reflection fallback.

Exit codes

Code Meaning
0 Success (all modes); -v; -h; validate passed; auditing all images; extracting an image with no files (ErrIsoNoFiles is treated as success); create succeeded; checksum matched.
1 Any error: usage, invalid flag values, mode conflicts, file open failures, per-ISO exceptions, invalid ISO, validate exceptions, CISO header errors.
2 Validation failure: validate command when the conversion does not pass, or -r --validate on mismatch (--validate-strict retained for parity; mismatches exit 2 with or without it).

Note

err is a single accumulator across a batch: a later ISO can overwrite an earlier exit code. Errors on one ISO do not stop processing of the remaining ISOs. One exception: an existing <name>.iso.old during rewrite is logged as an error but does not change the exit code — the ISO is skipped and processing continues.

Batch / multi-ISO processing

  • -l, -t, -x, -r, -V, checksum, hash and verify-dat accept multiple ISO files.
  • --jobs 1..64 runs collection verbs over images in parallel; output order is the same as --jobs 1 (including JSON arrays). Extract with one explicit -d destination stays sequential to avoid two images sharing an output tree; omit -d (per-image directories) to parallelize extraction.
  • -i, --md5, --sha256, --copy-out, --copy-in, and validate operate on a single ISO.
  • --video/--random/--seed/--wipe/--trim/--petrify/--update/--zar/--all/--best/--compress are batch modes (run via RunRedumpBatch) with -o single-file guard.
  • Per-ISO counters reset for each image; cumulative counters (TotalFilesAllIsos, TotalBytesAllIsos) span the whole run.
  • Per-ISO summary (on success):
    • tree: N files, M bytes
    • others: N files in <path> total M bytes
    • checksum: hex tab path
  • Batch summary when more than one ISO was processed: N files in K xiso's total M bytes.
  • If any warning was issued: WARNING: Warning(s) were issued during execution--review stderr!

Optimized-tag detection

Before processing each ISO the tool reads the optimized tag — the 24-byte string in!xiso!2.7.1 (01.11.14) at byte offset 31337 (minimum 7-byte prefix in!xiso is sufficient). Consequences:

  • Rewrite mode: an optimized image is skipped with "already optimized, skipping...". Otherwise the source is renamed to <name>.iso.old (aborting if that file already exists) and a new optimized ISO is written; -D deletes the .old afterwards.
  • Extract/list/tree/checksum: the tag selects the directory right-offset calculation (llCompat = !optimized). Images without the tag use the legacy linked-list-compatible layout; images with the tag use the optimized layout.
  • Audit (-V): the tag is reported (Optimized: yes/no) but does not fail the audit, so raw/unconverted dumps pass; --is-optimized is the strict tag check.
  • With --prepend-sectors, the tag shifts together with the game partition.

Examples

# Extract one ISO to a specific directory
XISOSharp -d ./out game.iso

# Unpack the whole image (auto-named output directory)
XISOSharp --unpack game.iso

# Unpack to a specific destination
XISOSharp --unpack game.iso ./out

# Resume an interrupted unpack (skips files already on disk)
XISOSharp --skip-existing --unpack game.iso ./out

# Extract several ISOs (default mode)
XISOSharp game1.iso game2.iso game3.iso

# Create with a custom name, skipping $SystemUpdate and temp files
XISOSharp -s -X "**/*.tmp" -c ./game_files custom_name.iso

# Create a Redump-style image (game partition at the XGD2 offset)
XISOSharp -c --prepend-sectors 129824 ./game_files redump.iso

# Pack a directory into an ISO (alias-style convenience)
XISOSharp --pack ./game_files

# Repack an existing ISO in place (optimizes it, keeping a .old copy)
XISOSharp --pack game.iso

# Extract a Redump image whose game partition starts at a nonstandard offset
XISOSharp --skip-sectors 129824 -d ./out redump.iso

# Optimize (rewrite) an ISO, then validate the result
XISOSharp -r --validate --validate-strict game.iso

# Rewrite to a custom output name (relative to -d, or rooted and used as-is)
XISOSharp -r -d ./optimized -o game_opt.iso game.iso
XISOSharp -r -o /archive/game_opt.iso game.iso

# Validate two images against each other
XISOSharp validate --validate-checksums --validate-report report.json source.iso rebuilt.iso

# Deep-audit several images
XISOSharp -V game1.iso game2.iso

# Batch-process every ISO in a directory (recursive)
XISOSharp -r --batch ./isos --batch-recursive
XISOSharp --batch ./isos -d ./extracted
XISOSharp --skip-existing --batch ./isos -d ./extracted  # resume interrupted bulk extract

# Hash all files in an image with SHA-256
XISOSharp --sha256 game.iso

# List the root directory of an image (non-recursive)
XISOSharp --ls game.iso

# List a subdirectory
XISOSharp --ls game.iso /media

# Sector map, sector ranges, optimized-tag probe
XISOSharp --sector-layout game.iso
XISOSharp --ranges game.iso
XISOSharp --is-optimized game.iso

# Repack a directory at an existing image's sector layout
XISOSharp --sector-layout --json game.iso > game.layout.json
XISOSharp -c ./game_dir game.iso --layout game.layout.json
# ... or from a compact "path=sector" text spec
XISOSharp --pack ./game_dir game.iso --layout layout.txt

# Show the Xbox 360 executable header of a game
# (title ID, entry point, region, media types, ...)
XISOSharp --xex-info game360.iso /default.xex

# Show the original-Xbox executable header + certificate
# (title ID/name, media, region, ...)
XISOSharp --xbe-info game.iso /default.xbe

# Read Xbox 360 XDBF title metadata (also used by `title-info`)
XISOSharp title-info game360.iso

# Extract an XBE title image or logo as PNG/DDS
XISOSharp --xbe-image game.iso /default.xbe --type title -o title.png
XISOSharp --xbe-image game.iso /default.xbe --type logo -o logo.dds

# Copy one directory out of an image
XISOSharp --copy-out game.iso /media ./media_out

# Patch one file into an image (replaces /config.ini; keeps game.iso.old backup)
XISOSharp --copy-in game.iso ./my-config.ini /config.ini

# --- Archival (Redump) ---

# Extract video partition (writes game.video.iso)
XISOSharp --video game.redump.iso

# Extract filler + seed, wipe & trim
XISOSharp --random game.redump.iso
XISOSharp --seed game.redump.iso          # XGD1 only
XISOSharp --wipe -o wiped.xiso game.redump.iso
XISOSharp --trim -o trimmed.xiso game.redump.iso
XISOSharp --all game.redump.iso           # all-of-the-above + video/wipe
XISOSharp --best game.redump.iso          # trim + wipe

# Petrify + update + zar
XISOSharp --petrify game.iso              # skeleton + .hash (SHA-1)
XISOSharp apply-skeleton game.skeleton.xiso ./files -o game-restored.iso --hash game.hash
XISOSharp --update game.redump.iso        # XGD3 su20076000_00000000
XISOSharp --zar -o game.zar game.iso
XISOSharp --zar-level 22 -o game-small.zar game.iso

# Inspect a Redump/XGD layout and generate a portable hash sidecar
XISOSharp disc-info game.redump.iso
XISOSharp disc-info game.redump.iso --json
XISOSharp file-hashes game.iso --algorithm sha256 -o game.sha256

# Xbox 360 metadata/thumbnail from a container or loose executable
XISOSharp title-info game.god
XISOSharp xex-image game.iso /default.xex --type thumbnail -o thumbnail.png
XISOSharp --xex-info default.xex --json
XISOSharp --xbe-info default.xbe --json

# Rebuild Redump from components (lossless round-trip)
XISOSharp rebuild x.iso video.iso filler.bin su20076000_00000000 -o rebuilt.redump.iso
XISOSharp rebuild x.iso video.iso --security-sectors sectors.txt -o rebuilt.redump.iso
XISOSharp rebuild game.zar video.iso filler.bin su20076000_00000000 -o rebuilt.redump.iso   # .zar sidecar as <xiso>

# With security sectors (rebuild only; 4096-sector ranges)
XISOSharp rebuild x.iso video.iso filler.bin su20076000_00000000 --security-sectors sectors.txt -o rebuilt.redump.iso

# --- xdvdfs parity ---

# Ordered remapping (wax captures, negation, dry-run, xdvdfs.toml)
XISOSharp build-image ./src -m "bin:/" -m "assets/**:/assets/{1}" -O out.iso
XISOSharp build-image -D -m "!secret/**" -m "**:/{0}" ./src
XISOSharp build-image -f xdvdfs.toml ./src -O out.iso

# Generate TOML spec
XISOSharp image-spec from -O dist/image.iso -m "bin:/" -m "assets:/{0}" xdvdfs.toml

# CISO compress / decompress (DEFLATE v1 + LZ4 v2)
XISOSharp compress ./game_dir game.cso --ciso-level 9
XISOSharp cso game.iso game.cso --ciso-version 2 --ciso-split 0
XISOSharp decompress game.cso game.iso
XISOSharp uncso game.cso
XISOSharp decso game.cso

# CCI compress / decompress (CCISharp, LZ4 or LZ4-HC sector blocks)
XISOSharp compress --format cci game.iso game.cci --cci-level 12 --jobs 4 --cci-split 0
XISOSharp cci game.iso game.cci --cci-split 0
XISOSharp decompress game.1.cci game.iso
XISOSharp uncci game.cci game.iso

# ZArchive input / conversion
XISOSharp -l game.zar
XISOSharp --unpack game.zar out/
XISOSharp checksum game.zar
XISOSharp convert game.zar game.iso

# Batch container conversion (compress / decompress / convert / split)
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

# SHA3-256 image checksum (deterministic, BTreeMap sorted)
XISOSharp checksum game.iso
XISOSharp checksum --silent game1.iso game2.iso
XISOSharp --checksum game.iso

Notes

  • The banner is XISOSharp v<version> for <win|linux|macos|cross-platform> - https://github.com/purelogiccode/XISOSharp (version from the MinVer build stamp, +build metadata trimmed).
  • -v prints the banner to stdout even under -Q; usage (-h) goes to stderr and is never suppressed by quiet modes.
  • Info/hash/copy-out/copy-in/audit/validate/checksum/filetime dispatch happens before the batch loop, so those modes ignore additional positional arguments beyond what they document.
  • Archival verbs (--video/--random/…/--zar/--all/--best/--compress) dispatch via RunRedumpBatch with shared ExpandIsoFiles (--jobs/--policy thread through the --zar path); rebuild has its own parser with --security-sectors/--sectors.
  • xdvdfs verbs (build-image/image-spec/compress/decompress/checksum/split/join) are detected as first token and handled before getopt parsing.
  • Container batch verbs (compress/decompress/convert/split) parse their own --batch, --batch-recursive, --skip-existing, --continue-on-error, --jobs and --output-name before the main parser, so the main-mode --batch restrictions do not apply to them.
  • Output progress uses carriage returns when writing to a terminal and newlines when stdout is redirected, so logs stay readable in CI.
  • Automatic update checks: every launch compares the running version against the latest GitHub release (at most one request per 24 h, cached in %LocalAppData%/XISOSharp/update-check.json). A newer release prints an [UPDATE] notice to stderr with the release URL and the matching release_<version>_<rid>.zip asset (win-x64, win-arm64, linux-x64, linux-arm64, MacOsX-x64, MacOsX-arm64), and offers to open the release page on interactive consoles. Skipped for -q/-Q/-v, test hosts, and XISO_NO_UPDATE_CHECK=1; never fails the run, never files a bug report.

See also: Getting Started · Validation · Redump & Disc Layouts · Archival · xdvdfs Compat · Compression · FAQ · Troubleshooting