Install and update

Hoku is free and published on GitHub Releases. You install it once and it stays in Applications like any other app.

Before you start: you need an Apple Silicon Mac. Releases aren’t built for Intel Macs. On an Intel Mac, build Hoku from source instead.

Install

Terminal (recommended)

Paste this into Terminal:

curl -fsSL https://raw.githubusercontent.com/joao-afonso-p/hoku/main/scripts/install.sh | bash

The install script:

1. downloads the latest release’s DMG and its SHA256SUMS.txt, and checks the SHA-256
2. checks the app inside: bundle identifier com.hoku.app and an intact code signature
3. quits Hoku if it’s running
4. replaces /Applications/Hoku.app, putting the old copy back if that fails
5. opens Hoku.

It never touches your index in ~/Library/Application Support/com.hoku.app, and it prints the index’s project and session counts before and after to show that. Because the script checks the download itself, macOS doesn’t show the “could not verify” prompt described in the DMG tab.

Options go after bash -s --:

curl -fsSL https://raw.githubusercontent.com/joao-afonso-p/hoku/main/scripts/install.sh | bash -s -- --version v0.2.0

Option	Effect
--version vX.Y.Z	Install that release instead of the latest
--dir ~/Applications	Install for your user only, if you can’t write to /Applications. The folder must exist.
--dmg FILE	Install a DMG you already downloaded. A SHA256SUMS.txt must be next to it.
--no-open	Don’t open Hoku afterwards

DMG

1. Download Hoku_<version>_aarch64.dmg from the latest release.

2. Open it and drag Hoku onto Applications.

3. Open Hoku from Applications. macOS says “Apple could not verify ‘Hoku’ is free of malware…”. Click Done, not Move to Trash.

4. Open System Settings → Privacy & Security, scroll to Security, and click Open Anyway next to “Hoku” was blocked. Confirm with your password or Touch ID.

5. Hoku opens. From now on it opens normally from Launchpad, Spotlight or the Dock.

You do this once per downloaded version.

Why macOS asks

Apple only opens downloaded apps without asking if they’re signed with a paid Apple Developer ID and notarized. Hoku doesn’t use the paid program. Releases are ad-hoc signed (the whole app is sealed, so macOS can tell if it was changed) but not notarized, so Gatekeeper asks you once. Releasing Hoku explains the details.

If macOS says Hoku is “damaged”, the download is incomplete or was changed. Delete it and download it again. Don’t work around that message.

Check a download

Each release has a SHA256SUMS.txt and a GitHub build provenance attestation. With both files in one folder:

shasum -a 256 -c SHA256SUMS.txt

With the GitHub CLI, you can also check that the DMG was built by Hoku’s own release workflow from this repository:

gh attestation verify Hoku_<version>_aarch64.dmg --repo joao-afonso-p/hoku

Neither replaces Apple’s malware scan. They show the file is the one the repository built.

Update

Hoku doesn’t update itself. To see which version you have, open Settings and look at the bottom, or choose Hoku → About Hoku.

• With the script: run the same install command again. If Hoku is running, it quits it, swaps in the new version and reopens it.
• By hand: quit Hoku, download the new DMG, and drag Hoku onto Applications, choosing Replace. Then approve it once in Privacy & Security as above.

Updating replaces only Hoku.app. Your projects, notes, favorites, follow-ups and positions on the map are in your index, which lives outside the app and carries over. The first launch of a new version upgrades the index in place.

After each update, macOS may ask again about iTerm or Terminal

The first time you use Go to terminal after an update, macOS may ask again whether Hoku can control iTerm or Terminal. An ad-hoc signature has no fixed developer identity, so macOS treats each version as a new app for that permission. Click Allow. You can remove the old entry in System Settings → Privacy & Security → Automation.

The documentation describes the latest release. If something here is missing from your copy of Hoku, update it.

Uninstall

See Your data: backup, reset, uninstall.