Repository navigation
Publishing to the Mod Index
Keep source, assets and license in your own repository. The index repository contains metadata only. Nothing in this guide publishes automatically.
Every release is signed with an Ed25519 key you own. The app refuses releases that are unsigned, signed with a key the index doesn't list for you, or whose archive doesn't match the listing.
- Generate an Ed25519 key pair. Keep the private key (raw or base64 file) outside your mod and out of git.
- Add
authors/<author>.jsonto the index in a PR:
{
"author": "alice",
"keys": [
{
"keyId": "alice:2026-11",
"publicKey": "BASE64_PUBLIC_KEY",
"validFrom": "2026-11-01T00:00:00Z",
"validUntil": "2028-01-01T00:00:00Z"
}
]
}keyId must start with <author>:. A first author key needs maintainer review; key changes need old-key endorsement or another review.
The signature covers the canonical JSON {api,app,id,sha256,version} for the release (api and app are the compatibility ranges, sha256 is the archive hash). index-entry builds and signs it for you.
- Validate and check the dry run:
betterfinder-mod validate ./my-mod. Review permissions and asset provenance. Keep editor files and build output out of the archive. - Package:
betterfinder-mod package ./my-mod --out /tmp/my-mod.bfmod. - Tag the reviewed commit in your repository and upload the exact
.bfmodbytes as a release asset. - Generate the listing and sign it:
betterfinder-mod index-entry /tmp/my-mod.bfmod \
--repo https://github.com/OWNER/REPO \
--release-url https://github.com/OWNER/REPO/releases/download/v1.0.0/my-mod.bfmod \
--tag v1.0.0 --commit FULL_40_CHARACTER_COMMIT \
--key-id alice:2026-11 --author-key ~/keys/alice.key \
--categories WORKFLOW --out mods/alice.my-mod--out can be a file or a directory (a directory gets listing.json). Use --signature BASE64 instead of --author-key if you sign elsewhere; without either the listing carries a placeholder signature and will fail.
- Check the listing against the archive before submitting:
betterfinder-mod validate /tmp/my-mod.bfmod --listing mods/alice.my-mod/listing.json --authors ../betterfinder-mod-index/authorsThis checks manifest identity and permissions, archive size and SHA-256, and the signature. --authors takes a key file or a directory; by default the CLI looks for authors/<author>.json next to the listing. Failures are BF7010 (listing doesn't match the package), BF7011 (bad signature), BF7012 (key not trusted for that author) and BF7013 (archive doesn't match the listing).
- Submit a PR with
mods/<author>.<name>/listing.json(and yourauthors/<author>.jsonthe first time) plus optional icon and screenshots. Explain every permission, the license, and the exact release, hash and key. Don't submit generated feed or signature edits.
Signing establishes who published a release, not that it is safe. Maintainers still verify artifact bytes, author identity and full preflight before promotion.
See permissions, CLI reference and the index's contribution instructions. The real world examples all went through this flow.
- Home
- Installing
- Building
- Replacing Finder
- Themes
- Keyboard Shortcuts
- FAQ
- Modding
- Getting Started
- Writing Mods in bfscript
- Writing Mods in TypeScript
- Permissions
- Hooks
- UI Surfaces
- Publishing to the Mod Index
- Using the MCP Server
- Troubleshooting
- Examples
- API Reference
- Manifest Reference
- Diagnostic Codes
- CLI Reference
- Reference Home
- Getting Started bfscript
- Getting Started TypeScript
- Getting Started JavaScript