sigil.yaml Manifest Reference

Source: schemas/sigil-schema.json (JSON Schema, draft-07).

Top-level

Property	Type	Required	Default	Description
spec	string	yes	-	Manifest schema version. Pinned to v1.0 for the MVP.
app	object	yes	-	(undocumented)
build	object	yes	-	(undocumented)
package	object	-	-	(undocumented)
sign	object	-	-	(undocumented)
publish	object	-	-	(undocumented)
updates	object	-	-	(undocumented)
installer	object	-	-	Branded Windows installer wizard config. Tokens are emitted at pack time by BrandTokenEmitter; WCAG-AA contrast is enforced against white text.
parameters	object	-	-	Install-time / pack-time parameter declarations consumed by the wrapper installer (Sprint 5c).
install_steps	array	-	-	Main install-time step list executed by the wrapper installer (Sprint 5c). Per-step parameter shapes are validated by the typed deserializer. Path and argument fields may use brace tokens — {install_dir}, {var.}, {param.}, {temp_dir}, payload://… — and {staging_dir}. {staging_dir} (register row R5) resolves at INSTALL time to a freshly created, randomly named private directory for this run, administrator-only when the installer is elevated, and is deleted when the run ends. Use it as the dest of an http_download whose file a later run_program launches: the engine then re-verifies that file's sha256 from a handle denying write and delete, holds that handle across the launch, and — for an artifact that declared signing — Authenticode-checks it immediately before starting it. A fixed, predictable download destination gets none of that, and can be both pre-planted and swapped after the checksum. Note that {staging_dir} in a post_install hook is a SEPARATE directory from the install body's, reclaimed when the hook phase ends; a binary the install body downloaded cannot be launched from a hook.
pre_install	array	-	-	Steps executed before the main install_steps block.
post_install	array	-	-	Steps executed after the main install_steps block.
uninstall	array	-	-	Steps executed at the start of setup.exe /Uninstall, BEFORE the rollback journal replays. Lets the manifest tear down services / scheduled tasks / external scripts that the install journal doesn't cover.

app

Property	Type	Required	Default	Description
id	string	yes	-	Reverse-DNS application id, e.g. com.example.MyApp.
name	string	yes	-	(undocumented)
version	string	yes	-	Semantic version (Semver 2.0.0).
publisher	string	yes	-	Display name or X.500 distinguished name (CN=...).
description	string	-	-	(undocumented)
homepage	string	-	-	(undocumented)

build

Property	Type	Required	Default	Description
source	string	yes	-	Path (relative to manifest) to the directory whose contents will be packaged.
include	array	-	-	Glob patterns (relative to source) to include. Defaults to ['*/'].
exclude	array	-	-	Glob patterns (relative to source) to exclude.
deterministic	boolean	-	True	Reproducible build: sort entries, fixed mtimes, no host metadata.

package

Property	Type	Required	Default	Description
formats	array	-	zip	(undocumented)
architectures	array	-	x64	(undocumented)
msix	object	-	-	(undocumented)

package.msix

Property	Type	Required	Default	Description
publisher	string	-	-	X.500 distinguished name; must match the signing cert subject.
logo	string	-	-	Path to a master logo (PNG, square). Sigil will resize for tiles.
capabilities	array	-	-	(undocumented)
runWack	boolean	-	False	If true, run the Windows App Certification Kit (appcert.exe) against the packed MSIX. Emits SIG0111 (warning) when WACK isn't installed and SIG0112 (error) when WACK reports failures. WBS 2.9.

sign

Property	Type	Required	Default	Description
provider	enum: none, local, azure-trusted-signing	-	none	(undocumented)
local	object	-	-	(undocumented)
azureTrustedSigning	object	-	-	(undocumented)

sign.local

Property	Type	Required	Default	Description
pfx	string	yes	-	Path to a .pfx file.
passwordEnv	string	-	-	Name of the environment variable holding the PFX password.
timestampUrl	string	-	http://timestamp.digicert.com	(undocumented)

sign.azureTrustedSigning

Property	Type	Required	Default	Description
endpoint	string	yes	-	(undocumented)
accountName	string	yes	-	(undocumented)
certificateProfile	string	yes	-	(undocumented)
tenantIdEnv	string	-	AZURE_TENANT_ID	(undocumented)
clientIdEnv	string	-	AZURE_CLIENT_ID	(undocumented)
clientSecretEnv	string	-	AZURE_CLIENT_SECRET	(undocumented)

publish

Property	Type	Required	Default	Description
github	object	-	-	(undocumented)

publish.github

Property	Type	Required	Default	Description
repo	string	yes	-	(undocumented)
tagPrefix	string	-	v	(undocumented)
draft	boolean	-	False	(undocumented)

updates

Property	Type	Required	Default	Description
channel	string	-	stable	Free-form label naming which channel manifest this app points at (e.g. 'stable', 'beta'). Purely descriptive: Sigil does not resolve or host channels itself.
manifestUrl	string	-	-	HTTPS URL of the signed channel manifest that /Update fetches to check for a newer version; its detached signature is expected at the same URL with '.sig' appended. Must be https:// (SIG0324) -- the signature URL is this string + '.sig', so a cleartext value drags the signature fetch onto cleartext with it. Re-checked before the fetch at update runtime. Omit to ship an installer with no update capability.
deltaTargets	integer	-	3	How many previous versions a future delta-patch generator would target. Parsed and schema-validated today, but not yet consumed by the update runtime -- full-package updates ship first (see the delta-update deferral ADR).
signingKey	string	-	-	Base64-encoded X.509 SubjectPublicKeyInfo (SPKI) DER of the ECDSA P-256 PUBLIC key that verifies the detached signature (manifestUrl + '.sig') on the fetched channel manifest. Embedded at pack time as the update runtime's trust anchor -- never a private key, and never a file path. Validated at pack time (SIG0325): the value must base64-decode AND import as a P-256 public key, so a file path or a wrong-curve key is refused here rather than failing at SIG0321 on every installed machine.

installer

Property	Type	Required	Default	Description
icon	string	-	-	Path (relative to the manifest) to a .ico file that becomes the produced setup.exe's Explorer icon. When omitted, the bundled default icon is used.
brand	object	-	-	(undocumented)
scope	string	-	auto	Install scope: per-user, per-machine, or auto-resolve (T12).
install_dir	string	-	-	Optional install-dir override; may reference {app.*} / {scope_root} tokens (T13).
license	LocalizedText	-	-	Either a plain string (treated as English) or a { "en": ..., "uk": ... } map. An en entry is required (SIG0290).
language	string	-	-	Optional fixed installer language tag (P9, gap G10) — the first link in the language-preference chain (installer.language -> /lang -> OS list -> en). An invalid tag is diagnosed (SIG0291).
require_signed_downloads	string	-	sign_declared	Whether a binary this installer pulls off the network -- an update package or a web-stub payload -- must be Authenticode-valid before it is launched (register row R45). sign_declared (default, and the historical behaviour) arms the check only when this manifest declares a sign block; that infers 'should downloads be verified' from 'did the publisher configure signing for their own output', which are different questions. always arms it regardless. always_verified_revocation additionally REFUSES a binary whose revocation status could not be established (register row R46) -- by default that is a warning, because refusing it would break installs behind a captive portal, on an air-gapped network, or inside a locked-down enterprise egress; turn it on when you know your audience is reliably online. Prerequisites are not governed by this setting: they are always checked, and carry their own per-prerequisite allow_unsigned opt-out. An unrecognized value is SIG0326.
options	object	-	-	Built-in configurable installer components (T8) plus app-defined custom components (P10, gap G11).
screens	array	-	-	Declared custom wizard screens over parameters (T9).
vars	object	-	-	Declarative variables (P1, gap G1): each entry is name: <expression> evaluated once at install-session start, in dependency order, and exposed as var. in when expressions / screen-field defaults and as a {var.} brace token in step paths and args. Expressions use the closed when grammar plus the read-only data-retrieval functions registry_read/env/file_version/installed_version; a var referencing a secret parameter inherits secretness. A reference cycle is a pack error (SIG0270).
hooks	object	-	-	Lifecycle hooks (P2, gap G2). Each phase is an ordered list of ordinary step records (typically run_program) that run OUTSIDE the rollback journal. WARNING: hooks have NO rollback obligations — their side effects are never recorded and never undone. A hook is governed only by its own on_failure: fail aborts the operation (the default for pre_install/pre_uninstall — the run stops before the journal opens / before the uninstall replays); continue logs and proceeds (the default for post_install/post_uninstall — the install is already committed and cannot be rolled back). Hook args may use {var.*} / {install_dir} tokens.
run_after_install	object	-	-	The program the Done screen's checked-by-default 'Launch ' checkbox starts, and the program a headless /silent /launch run starts (P2, gap G4). Always launched UNELEVATED — de-elevated to the user's medium-integrity token when the installer itself ran as admin.
prerequisites	array	-	-	First-class prerequisite units (P5, gap G6) — the declarative equivalent of Burn's ExePackage + DetectCondition. Each runs BEFORE the transactional install body and the pre_install hooks (and before the rollback journal opens): its detect expression is evaluated (skip when already satisfied), otherwise the source installer is acquired and run, and detect is re-evaluated to confirm it took effect. WARNING: prerequisites are NEVER journaled and are NOT rolled back — a shared machine dependency (VC++ redist, .NET runtime) must not be undone. An exit code of 3010 flags reboot-required (Done-screen notice + silent exit code 3010).
app_mutex	array	-	-	Named mutexes the application creates while it is running (P6, gap G7) — the Inno AppMutex equivalent. Before touching the install directory, setup opens each name; a mutex that opens means the app is running and the install/uninstall is blocked. This complements the Restart Manager sweep, which also finds processes holding files open in the install directory even when no mutex is declared. Blocked runs: the wizard shows a 'Close applications' screen; /silent exits with a dedicated code unless /closeapps is supplied. Use the exact name the app passes to CreateMutex, including any Global\ prefix.

installer.brand

Property	Type	Required	Default	Description
logo	string	-	-	(undocumented)
hero	string	-	-	(undocumented)
primaryColor	string	-	-	Wizard primary colour as #RRGGBB — primary buttons and accent fill. Feeds BrandTokenEmitter, which derives a full light+dark palette from this and accentColor at pack time. Omitted, it falls back to Sigil's default #1F2937. NOTE the camelCase spelling: primary_color was accepted by this schema until R80 and read by nothing, so a snake_case manifest packed a silently unbranded installer; it is now refused by additionalProperties.
accentColor	string	-	-	Wizard secondary accent as #RRGGBB — progress indication and links. Omitted, it falls back to Sigil's default #3B82F6. camelCase, for the reason given on primaryColor.

installer.options

Property	Type	Required	Default	Description
desktop_shortcut	InstallerOption	-	-	Built-in configurable installer component: shorthand boolean or an object.
start_menu	InstallerOption	-	-	Built-in configurable installer component: shorthand boolean or an object.
add_to_path	InstallerOption	-	-	Built-in configurable installer component: shorthand boolean or an object.
file_associations	FileAssociationOption	-	-	file_associations component: shorthand boolean or an object with extensions.
components	array	-	-	App-defined custom components (P10, gap G11) — the Inno [Tasks] equivalent. Each generates NO install step of its own; it exists only as option. in the expression engine, gating arbitrary steps / step groups via their when. Rendered as checkboxes on the Options screen after the built-ins, in declared order.

installer.hooks

Property	Type	Required	Default	Description
pre_install	HookPhase	-	-	An ordered list of lifecycle-hook steps (P2). Accepts the SAME closed catalog of 18 step types as install_steps — the four config/network types were missing here until R81, which was drift from the lane that added them, never a policy. What differs is the journal, not the catalog: hooks run OUTSIDE the rollback journal, so their side effects are never recorded and never undone, and each step is governed only by its own on_failure (fail or continue; rollback is refused — there is nothing to unwind). See installer.hooks.
post_install	HookPhase	-	-	An ordered list of lifecycle-hook steps (P2). Accepts the SAME closed catalog of 18 step types as install_steps — the four config/network types were missing here until R81, which was drift from the lane that added them, never a policy. What differs is the journal, not the catalog: hooks run OUTSIDE the rollback journal, so their side effects are never recorded and never undone, and each step is governed only by its own on_failure (fail or continue; rollback is refused — there is nothing to unwind). See installer.hooks.
pre_uninstall	HookPhase	-	-	An ordered list of lifecycle-hook steps (P2). Accepts the SAME closed catalog of 18 step types as install_steps — the four config/network types were missing here until R81, which was drift from the lane that added them, never a policy. What differs is the journal, not the catalog: hooks run OUTSIDE the rollback journal, so their side effects are never recorded and never undone, and each step is governed only by its own on_failure (fail or continue; rollback is refused — there is nothing to unwind). See installer.hooks.
post_uninstall	HookPhase	-	-	An ordered list of lifecycle-hook steps (P2). Accepts the SAME closed catalog of 18 step types as install_steps — the four config/network types were missing here until R81, which was drift from the lane that added them, never a policy. What differs is the journal, not the catalog: hooks run OUTSIDE the rollback journal, so their side effects are never recorded and never undone, and each step is governed only by its own on_failure (fail or continue; rollback is refused — there is nothing to unwind). See installer.hooks.

installer.run_after_install

Property	Type	Required	Default	Description
path	string	yes	-	Program to launch. May use {install_dir} / {var.*} / payload:// tokens.
args	array	-	-	Optional arguments; each may use the same tokens.

parameters.<name>

Property	Type	Required	Default	Description
type	string	yes	-	(undocumented)
default	-	-	-	(undocumented)
values	array	-	-	(undocumented)
install_time	boolean	-	False	(undocumented)
description	LocalizedText	-	-	Either a plain string (treated as English) or a { "en": ..., "uk": ... } map. An en entry is required (SIG0290).
pattern	string	-	-	(undocumented)
min	integer	-	-	(undocumented)
max	integer	-	-	(undocumented)
screen	string	-	-	Optional wizard page label. Parameters that share a screen value are grouped onto the same Install Options screen in the wrapper installer. Parameters without a screen value land on a default 'Install Options' page after all named screens.
source	object	-	-	Dynamic options source. The wizard fetches url at install time, parses JSON, and populates a ComboBox with the items at items_path keyed by value_property / labelled by label_property.

parameters.<name>.source

Property	Type	Required	Default	Description
url	string	yes	-	HTTPS URL fetched at install time. Must be https:// (SIG0323): the values it returns become parameter values, and parameter values are substituted into install-step fields -- paths, registry coordinates, arguments -- that execute elevated. Re-checked at install time against the substituted URL.
items_path	string	yes	-	(undocumented)
value_property	string	yes	-	(undocumented)
label_property	string	yes	-	(undocumented)

Definition: LocalizedText

Either a plain string (treated as English) or a { "en": ..., "uk": ... } map. An en entry is required (SIG0290).

Definition: Parameters

Install-time / pack-time parameter declarations consumed by the wrapper installer (Sprint 5c).

Definition: InstallStep

Property	Type	Required	Default	Description
id	string	yes	-	(undocumented)
type	string	yes	-	(undocumented)
when	string	-	-	(undocumented)
on_failure	string	-	-	What to do when this step fails. rollback (the default) aborts and replays the rollback journal in reverse across every phase that ran; continue logs and proceeds. There is no abort-without-rollback mode for a journalled phase: fail was accepted until it was removed in R78, where it had always behaved identically to rollback, and is now refused with SIG0233.
allow_outside_install_dir	boolean	-	-	Opt this step out of the install_dir destination-containment rule (register row R16). Accepted only by the step types whose destination is contained: file_copy, directory_create, file_delete, directory_delete, http_download, ini_write, json_edit, xml_edit. On any other step type it is an unrecognized field (SIG0231) and has no effect. Use it for deliberate out-of-tree writes, such as a machine-wide config under ProgramData. It does NOT relax the privileged-target rule on service_install / scheduled_task_create / com_register / firewall_rule, and it does not suppress the unresolved-token failure, which applies to every path field and has no opt-out. Note there is no %VAR% expansion in a step path.

Definition: InstallerOption

Built-in configurable installer component: shorthand boolean or an object.

Definition: FileAssociationOption

file_associations component: shorthand boolean or an object with extensions.

Definition: CustomComponent

Property	Type	Required	Default	Description
name	string	yes	-	The component key — a bare identifier, unique among components and not colliding with a built-in component or a declared parameter (SIG0300). Referenced as option. in step when clauses.
label	LocalizedText	yes	-	The checkbox caption (localizable — a plain string or an { en: ..., de: ... } map).
description	LocalizedText	-	-	Optional secondary caption shown under the checkbox (localizable).
default	boolean	-	False	The checkbox's initial (checked) state.
locked	boolean	-	False	When true the row renders disabled and is always applied at its default; a CLI override is ignored (logged).
when	string	-	-	Optional applicability gate (a when-grammar expression). When it evaluates false the row is hidden and option. resolves to false. May reference param. / scope / system. but not var.* (v1).

Definition: Prerequisite

Property	Type	Required	Default	Description
name	string	yes	-	Human label shown on the wizard progress row and in the log ('Installing …').
detect	string	yes	-	A when-grammar expression that is true when the prerequisite is ALREADY satisfied (typically a registry_read / file_version / registry_exists check). Evaluated before install (skip if true) and again after (fail if still false).
source	string	yes	-	The installer to run when detect is false: a payload://… path (bundled in the package) or an https://… URL (downloaded at install time). Args may use {var.*} / {install_dir} tokens.
sha256	string	-	-	SHA-256 integrity checksum (hex). REQUIRED for an https:// source (a download without it is refused, SIG0280); ignored for a payload:// source.
args	array	-	-	Arguments passed to the source installer (typically /quiet /norestart).
exit_codes_ok	array	-	-	Exit codes treated as success; defaults to [0]. An accepted code of 3010 additionally flags reboot-required.
scope_required	string	-	-	Requires the install to run in this scope; a mismatch with the resolved scope is a diagnostic at session start. Omit to accept any scope.
timeout_seconds	integer	-	-	Optional per-prerequisite run timeout, in seconds.
allow_unsigned	boolean	-	False	Launch this prerequisite even when its Authenticode signature does not establish trust. A DOWNLOADED prerequisite installer is signature-checked immediately before it is run and refused if it is unsigned or its signature is invalid; unsigned redistributables are common and legitimate, so this opts out of that check. It NEVER waives a revoked or explicitly distrusted certificate, and the sha256 is enforced either way. Ignored for a payload:// source, which is not checked at all — its integrity comes from the package's own signature.

Definition: HookPhase

An ordered list of lifecycle-hook steps (P2). Accepts the SAME closed catalog of 18 step types as install_steps — the four config/network types were missing here until R81, which was drift from the lane that added them, never a policy. What differs is the journal, not the catalog: hooks run OUTSIDE the rollback journal, so their side effects are never recorded and never undone, and each step is governed only by its own on_failure (fail or continue; rollback is refused — there is nothing to unwind). See installer.hooks.

Definition: InstallerScreen

Property	Type	Required	Default	Description
id	string	yes	-	(undocumented)
title	LocalizedText	yes	-	Either a plain string (treated as English) or a { "en": ..., "uk": ... } map. An en entry is required (SIG0290).
subtitle	LocalizedText	-	-	Either a plain string (treated as English) or a { "en": ..., "uk": ... } map. An en entry is required (SIG0290).
when	string	-	-	(undocumented)
fields	array	yes	-	(undocumented)

Definition: ScreenField

A screen field: a bare parameter-name string or a { param, widget } object.