Skip to content

Sigil documentation

User-facing docs for the sigil CLI and its manifest format. Build, test and repo conventions live in ../AGENTS.md; ../CONTRIBUTING.md covers what to report and why code contributions are closed.

Start here

  • Getting started — install Sigil and run your first init → validate → pack cycle in under five minutes.

Reference

  • CLI reference — every sigil subcommand, its options, and an example. Auto-generated from the live command tree.
  • Manifest reference — every key in sigil.yaml, with type, default, and description. Auto-generated from schemas/sigil-schema.json.
  • setup.exe reference — every runtime flag the produced installer/uninstaller accepts (/S, /D=, /PName=Value, exit codes, …). Hand-written — see the page for why it cannot be generated.

Guides

How-to guides for each shipped feature. Start with the wizard guide if you're building a Windows installer; start with packaging formats if you're not sure which output format you need.

  • Installer wizard — branded wizard host, brand slots, custom screens (installer.screens[]), install icon.
  • Parameters — install-time parameters, types, dynamic dropdowns.
  • Install steps — every step type with a worked example.
  • Uninstaller — auto-generated uninstall.exe + Add/Remove Programs entry.
  • Upgrades & downgrades — version-aware install, /force-downgrade, install-dir preservation.
  • Updates — the updates: block, signed channel manifests, /Update exit codes, and the web installer (--payload web).
  • Prerequisites — detect-then-install dependency units (VC++ redist, .NET runtime).
  • Packaging formats — MSIX vs ZIP vs EXE-wrapper.
  • Signing — local PFX or Azure Trusted Signing.
  • Conditional installs — when: expressions and rollback.
  • Localization — installer.language, /lang, the LocalizedText shape, and known limitations.

Concepts

  • Architecture overview — what Sigil does, how the pack → sign → publish → update pipeline fits together, and the short list of locked-in technical choices.

Architecture decision records

The ADRs in architecture/ record why each load-bearing choice was made. Several are user-facing contracts, not just internal rationale:

Migrating from another tool

A note on the auto-generated files

cli-reference.md, manifest-reference.md, and (when wired) api/ are regenerated from the code, schema, and XML doc comments. Do not edit them by hand — your changes will be overwritten on the next CI run. To update them, edit the source of truth (the Description strings on CLI commands, the description fields in the JSON schema, or the /// comments on public types) and re-run scripts/docs/generate-*.ps1.

This is enforced, not merely asked: the docs workflow regenerates both pages on every PR that touches src/, schemas/ or docs/, and fails if git status --porcelain docs/ is non-empty afterwards. A hand edit to either page therefore fails CI even when it is correct.