Skip to main content

​
Installing a release binary

Download the archive for your system from the Releases page (under Assets, on the latest release). Not sure which file you need? See the FAQ. Each archive contains two binaries directly: obsidianlog (the CLI) and obsidianlog-ingest (the standalone ingest server). There’s no installer and no dependencies to install separately. Whether extracting it lands those two files in their own folder depends on how you extract it. Double-clicking the archive (or your file manager’s Extract option) creates a new folder named after it automatically. Extracting from a raw tar command doesn’t, it dumps the files into whatever directory you’re already in. The commands below account for both, so you end up in a tidy folder either way.
Double-click the downloaded .tar.gz file (or use your file manager’s Extract option). It extracts into a new folder named after the archive. Open that folder, open a terminal there, and run:
On macOS, the quickest way to open the right folder in Terminal: open Terminal, type cd (including the space), then drag the extracted folder from Finder into the Terminal window and press Enter.Prefer to do the extraction from a terminal too?
The exact filename depends on which release and target you downloaded, matching what you got from the Releases page. The chmod step on macOS/Linux is needed because the executable bit isn’t always preserved inside the archive.
obsidianlog is a command-line tool, not a GUI app. The commands above need an actual terminal (Terminal on macOS, PowerShell or Windows Terminal on Windows, your terminal app on Linux). Double-clicking the binary itself does not start setup: it has no command to run, so it prints the help screen and exits. Open a terminal, change into the extracted folder, then run ./obsidianlog init (or .\obsidianlog.exe init on Windows).
The first time you run it, your OS may flag it as unsigned, since these binaries aren’t code-signed today:
Gatekeeper blocks it. The most reliable fix, especially for these command-line binaries, is to clear the quarantine flag directly in a terminal:
Prefer the GUI instead? The order matters here: right-click obsidianlog in Finder and choose Open once (this attempt gets blocked, that’s expected, it’s what registers the binary with macOS). Then go to System Settings → Privacy & Security, scroll to the Security section, and click Open Anyway next to the message naming obsidianlog. That button only appears after a blocked attempt, not before, so doing this step first won’t show it.

​
Archive your first log and get it back

The CLI wraps setup, ingestion, retrieval, and integrity checking. These four steps take under a minute and use --non-interactive, which always picks the local backend and skips every setup question, the fastest way to see the whole loop work. Omit that flag if you’d rather answer each question yourself.
Two terminals, both open in the folder you extracted. Leave the first running serve; use the second for everything else.1. Set up. Generates the encryption key and writes config.toml.
You’ll see:
2. Start the server.
The terminal won’t return to a prompt after this, it keeps running until you stop it. That’s expected, leave it running and use your second terminal for the rest.3. In the second terminal, send a log.
You should see 200 on its own line. That’s the only output: a successful ingest returns an empty response, -s hides curl’s progress meter, and -w '%{http_code}\n' prints the status code so you can tell it worked. If you see an error message and a code like 400 instead, the server rejected the log, and the message says why.4. Query it back.
5. Verify the hash chain.
See the full CLI reference for every command’s flags.
On macOS, init will prompt at most once for your login-keychain password. This is the OS asking permission for obsidianlog to store the credentials it just generated, not an ObsidianLog password. Click Always Allow rather than just Allow, so later serve/query/verify runs read them without prompting again.
You’ve now archived a real log, encrypted and hash-chained, and gotten it back out again, the same loop a production deployment runs continuously.

​
What’s next