id = "ipsw"
name = "ipsw"
homepage = "https://blacktop.github.io/ipsw/"
description = "A command-line tool for researching and reverse engineering Apple operating systems."
executables = ["ipsw"]

[dotfiles]

# https://github.com/blacktop/ipsw/blob/master/www/docs/getting-started/configuration.md
# documents ~/.config/ipsw/config.yml (and the command's default config.yaml
# path) as the user config on macOS; the same source lists the platform paths.
paths = ["~/.config/ipsw/config.yaml", "~/.config/ipsw/config.yml"]
exclude = []
secret = []
side_effect = false

# The documented download.ipsw.output setting is an absolute local storage
# path, so preserve it only for backup/review rather than applying it.
[[dotfiles.machine_lines]]
file = "~/.config/ipsw/config.yaml"
match = { key_path = ["download.ipsw.output"] }
scope = "backup"

[commands]
format = 1
label = "ipsw"
description = "Download, inspect and extract Apple firmware. Covers 'download ipsw', 'info' and 'extract'; the many other subcommands (dyld, macho, kernel, ...) are not covered."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.subcommand]]
path = ["download", "ipsw"]
label = "Download IPSWs"
description = "Download IPSW files (or just URLs, kernelcache or dyld cache) from ipsw.me. Filters by device, build or version."

[[commands.subcommand.source]]
id = "docs"
kind = "manual"
url = "https://raw.githubusercontent.com/blacktop/ipsw/master/www/docs/cli/ipsw/download/ipsw.md"
revision = "master 2026-10-27"
evidence = """
  -b, --build string             iOS BuildID (i.e. 16F203)
  -y, --confirm                  do not prompt user for confirmation
  -d, --device string            iOS Device (i.e. iPhone11,2)
      --dyld                     Extract dyld_shared_cache(s) from remote IPSW
      --kernel                   Extract kernelcache from remote IPSW
      --latest                   Download latest IPSWs
      --macos                    Download macOS IPSWs
  -o, --output string            Folder to download files to
  -u, --urls                     Dump URLs only
  -v, --version string           iOS Version (i.e. 12.3.1)
"""

[[commands.subcommand.field]]
id = "device"
label = "Device"
description = "Product type, for example iPhone15,2."
type = "string"
option = ["--device", "-d"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "version"
label = "OS version"
type = "string"
option = ["--version", "-v"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "build"
label = "Build ID"
type = "string"
option = ["--build", "-b"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "latest"
label = "Latest only"
type = "boolean"
option = ["--latest"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "macos"
label = "macOS IPSWs"
type = "boolean"
option = ["--macos"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "urls"
label = "URLs only"
description = "Print the download URLs instead of downloading."
type = "boolean"
option = ["--urls", "-u"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "kernel"
label = "Only kernelcache"
description = "Extract the kernelcache from the remote IPSW."
type = "boolean"
option = ["--kernel"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "dyld"
label = "Only dyld_shared_cache"
type = "boolean"
option = ["--dyld"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "confirm"
label = "Skip confirmation"
type = "boolean"
option = ["--confirm", "-y"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "output"
label = "Output folder"
type = "path"
option = ["--output", "-o"]
path = { kind = "directory", role = "output" }
sources = ["docs"]

[[commands.subcommand.task]]
id = "latest_for_device"
label = "Latest IPSW for a device"
fields = ["device", "latest", "output", "confirm"]
required = ["device"]
set = { latest = [true] }

[[commands.subcommand.task]]
id = "list_urls"
label = "List download URLs"
fields = ["device", "version", "build", "macos", "urls"]
required = ["device"]
set = { urls = [true] }

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["device", "version", "build", "latest", "macos", "urls", "output"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["kernel", "dyld", "confirm"]

[[commands.subcommand]]
path = ["info"]
label = "Show IPSW info"
description = "Display information about an IPSW or OTA file."

[[commands.subcommand.source]]
id = "docs"
kind = "manual"
url = "https://raw.githubusercontent.com/blacktop/ipsw/master/www/docs/cli/ipsw/info.md"
revision = "master 2026-10-27"
evidence = """
ipsw info <IPSW> [flags]
  -j, --json           Output as JSON
  -l, --list           List files in IPSW/OTA
  -r, --remote         Extract from URL
"""

[[commands.subcommand.field]]
id = "ipsw"
label = "IPSW or OTA"
type = "path"
position = 0
min = 1
path = { kind = "file", role = "input", must_exist = true }
sources = ["docs"]

[[commands.subcommand.field]]
id = "json"
label = "JSON output"
type = "boolean"
option = ["--json", "-j"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "list"
label = "List contained files"
type = "boolean"
option = ["--list", "-l"]
sources = ["docs"]

[[commands.subcommand.task]]
id = "info"
label = "Show info"
fields = ["ipsw", "json", "list"]
required = ["ipsw"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["ipsw", "json", "list"]

[[commands.subcommand]]
path = ["extract"]
label = "Extract components"
description = "Extract the kernelcache, dyld_shared_cache, DeviceTree or other parts from an IPSW or OTA."

[[commands.subcommand.source]]
id = "docs"
kind = "manual"
url = "https://raw.githubusercontent.com/blacktop/ipsw/master/www/docs/cli/ipsw/extract.md"
revision = "master 2026-10-27"
evidence = """
ipsw extract <IPSW/OTA | URL> [flags]
      --dtree                   Extract DeviceTree
  -d, --dyld                    Extract dyld_shared_cache
  -a, --dyld-arch stringArray   dyld_shared_cache architecture to extract
  -k, --kernel                  Extract kernelcache
  -o, --output string           Folder to extract files to
  -p, --pattern string          Extract files that match regex
      --sep                     Extract sep-firmware
"""

[[commands.subcommand.field]]
id = "ipsw"
label = "IPSW or OTA"
type = "path"
position = 0
min = 1
path = { kind = "file", role = "input", must_exist = true }
sources = ["docs"]

[[commands.subcommand.field]]
id = "kernel"
label = "Kernelcache"
type = "boolean"
option = ["--kernel", "-k"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "dyld"
label = "dyld_shared_cache"
type = "boolean"
option = ["--dyld", "-d"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "dyld_arch"
label = "dyld architectures"
type = "string"
option = ["--dyld-arch", "-a"]
multiple = true
suggestions = [{ value = "arm64e", label = "arm64e" }]
sources = ["docs"]

[[commands.subcommand.field]]
id = "dtree"
label = "DeviceTree"
type = "boolean"
option = ["--dtree"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "sep"
label = "SEP firmware"
type = "boolean"
option = ["--sep"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "pattern"
label = "File regex"
description = "Extract files from the IPSW zip whose names match this regex."
type = "string"
option = ["--pattern", "-p"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "output"
label = "Output folder"
type = "path"
option = ["--output", "-o"]
path = { kind = "directory", role = "output" }
sources = ["docs"]

[[commands.subcommand.task]]
id = "kernelcache"
label = "Extract kernelcache"
fields = ["ipsw", "kernel", "output"]
required = ["ipsw"]
set = { kernel = [true] }

[[commands.subcommand.task]]
id = "dyld_cache"
label = "Extract dyld_shared_cache"
fields = ["ipsw", "dyld", "dyld_arch", "output"]
required = ["ipsw"]
set = { dyld = [true] }

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["ipsw", "kernel", "dyld", "dyld_arch", "output"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["dtree", "sep", "pattern"]