@todesktop/create-release-metadata

Create signed release metadata files for ToDesktop Installer.

Prerequisites

Install minisign (required)

This tool requires the native minisign command to generate keys and sign files:

# View installation instructions
npx @todesktop/create-release-metadata --install-minisign
# On macOS
brew install minisign
# On Ubuntu/Debian
apt install minisign
# On Windows# Download from https://jedisct1.github.io/minisign/

Generate signing key pair with minisign

Generate a new signing key pair using minisign:

# Generate a new signing key pair
minisign -G
# This will create minisign.key (secret key) and minisign.pub (public key)# or
minisign -G -p minisign.pub -s minisign.key

Usage

CLI

# Basic usage
npx @todesktop/create-release-metadata \
--secret-key minisign.key \
MyApp-1.2.3-arm64.zip MyApp-1.2.3-x64.zip
# With release notes
npx @todesktop/create-release-metadata \
--secret-key minisign.key \
--release-notes-file release-notes.md \
MyApp-1.2.3-arm64.zip MyApp-1.2.3-x64.zip
# With expiration date
npx @todesktop/create-release-metadata \
--secret-key minisign.key \
--expires "2099-12-31T23:59:59Z" \
MyApp-1.2.3-arm64.zip MyApp-1.2.3-x64.zip
# For a beta release
npx @todesktop/create-release-metadata \
--secret-key minisign.key \
--stage beta \
MyApp-1.2.3-arm64.zip MyApp-1.2.3-x64.zip
# Custom output filename (overrides default manifest-{stage}-{platform}.json)
npx @todesktop/create-release-metadata \
--secret-key minisign.key \
--output-filename "release.json" \
MyApp-1.2.3-arm64.zip MyApp-1.2.3-x64.zip
# Provide password for the minisign key (for automation)
npx @todesktop/create-release-metadata \
--secret-key minisign.key \
--password "my-secure-key-password" \
MyApp-1.2.3-arm64.zip MyApp-1.2.3-x64.zip
# Show detailed progress information
npx @todesktop/create-release-metadata \
--secret-key minisign.key \
--verbose \
MyApp-1.2.3-arm64.zip MyApp-1.2.3-x64.zip

If you don't provide a password via the --password option, the tool will allow you to enter it interactively when minisign prompts for it.

Verifying signatures

Verify the generated manifest signature using the minisign utility:

# Verify the manifest file
minisign -Vm manifest-latest-mac.json -p minisign.pub

Example output of successful verification:

Signature and comment signature verified
Trusted comment: timestamp:1655234567 filename:manifest-latest-mac.json

API

import{createReleaseMetadata}from"@todesktop/create-release-metadata";asyncfunctioncreateRelease(){constmanifestPath=awaitcreateReleaseMetadata({distributables: ["MyApp-1.2.3-arm64.zip","MyApp-1.2.3-x64.zip"],secretKeyPath: "path/to/minisign.key",releaseNotes: "What's new in this release:\n- Feature A\n- Bug fix B",expires: "2099-12-31T23:59:59Z",// Optional: provide password for the minisign keypassword: "my-secure-key-password",// Optional: show detailed progress informationverbose: true,});console.log(`Created manifest at ${manifestPath}`);}

Manifest Format

The manifest is output as JSON with a nested artifacts structure, organized by artifact type (zip/dmg) and architecture:

{
"version": "1.2.3",
"schemaVersion": 1,
"releaseDate": "2024-03-20T10:00:00.000Z",
"expires": "2099-12-31T23:59:59Z",
"artifacts": {
"zip": {
"arm64": {
"path": "MyApp-1.2.3-arm64.zip",
"sha512": "abcdef1234567890...",
"size": 123456789
},
"x64": {
"path": "MyApp-1.2.3-x64.zip",
"sha512": "0987654321fedcba...",
"size": 123456789
}
}
},
"releaseNotes": "What's new in this release:\n- Feature A\n- Bug fix B"
}

Signatures are stored as external .minisig files alongside each artifact (e.g., MyApp-1.2.3-arm64.zip.minisig).

Important:

• Version is automatically extracted from the filename (e.g., MyApp-1.2.3-arm64.zip → 1.2.3). This includes prerelease tags like 1.2.3-beta.1. Use --app-version only if you need to override the detected version.
• Architecture must be detectable from the filename. Include one of: arm64, aarch64, x64, x86_64, amd64, x86, ia32, i386, or universal.
• Artifact type is determined by the file extension. Supported types: .zip, .dmg.

Options

Option	CLI	API	Description
--secret-key <path>	-k	secretKeyPath	Path to the minisign secret key
--release-notes <text>	-n	releaseNotes	Release notes in Markdown format
--release-notes-file <path>		releaseNotesPath	Path to a file containing release notes
--app-version <version>		appVersion	Version of the application (auto-detected from filename by default)
--platform <platform>		platform	Platform to create metadata for (default: mac)
--stage <stage>		stage	Release stage, e.g., latest, beta, stable (default: latest)
--output-dir <path>	-o	outputDir	Directory where metadata files will be written
--output-filename <name>		outputFilename	Output filename (default: manifest-{stage}-{platform}.json)
--expires <timestamp>		expires	Expiration date in ISO 8601 format
--password <password>		password	Password for the minisign secret key (optional)
--verbose		verbose	Show detailed progress information during execution
--install-minisign		N/A	Show instructions for installing minisign

License

MIT