Documentation menu

Installer and release channels

scripts/install is flog's canonical POSIX installer. https://flog.run/install serves that file byte-for-byte; the website does not copy or reimplement it. For executable self-updates, see the flog update command summary.

Once an initial public stable Release is promoted, the normal command is:

curl -fsSL https://flog.run/install | sh

The script supports Linux and macOS on amd64 and arm64. It requires curl, tar, awk, tr, wc, and either sha256sum or shasum. It installs to $HOME/.local/bin/flog by default. If that directory is not already on PATH, it appends a literal PATH line to an existing writable, regular bash (.bashrc or .bash_profile), zsh (.zshrc), or fish (config.fish) profile, and prints a reload command. Existing equivalent lines, marked or unmarked, are left alone. If there is no suitable profile, it prints manual instructions. A custom FLOG_INSTALL_DIR is never interpolated into profile shell code. Profile updates happen only after a successful installation; the installer never uses sudo or guesses a privileged destination.

Like Bun's installer, the profile update is an append, not an atomic no-follow operation. Checks reject symlinks that are present when inspected, but a symlink swapped in just before the append could redirect the write. Concurrent regular-file edits are not replaced, although simultaneous PATH edits may still produce duplicate lines. Avoid piping the installer into a shell in an environment where another process can alter your profile files.

Installer controls#

  • FLOG_INSTALL_DIR=/absolute/path selects an explicit destination.
  • FLOG_VERSION=1.2.3 installs one exact historical or prerelease version and bypasses the mutable channel index.
  • FLOG_CHANNEL=next selects an immutable prerelease Release channel. FLOG_CHANNEL=unstable selects the rolling development channel when its public feed has been enabled. The default is stable. A channel cannot be combined with FLOG_VERSION.
  • FLOG_RELEASES_URL=https://mirror.example/releases selects a compatible manifest origin.
  • FLOG_ALLOW_HTTP=1 permits HTTP for isolated local tests. Production use must retain HTTPS; without this opt-in, HTTP manifests, artifacts, and redirect targets are rejected.

Manifest protocol#

The protocol is strict newline-terminated, tab-separated text so the installer can parse it without jq, Python, Node, or sourced shell code. Unknown, duplicate, missing, malformed, CR-containing, and NUL-containing records are rejected by the Go tooling. The shell parser independently checks every record it consumes.

The mutable https://flog.run/releases/channels.v1 has this shape:

flog-channels-v1
stable	1.2.3
prerelease	next	1.3.0-pre.2

It contains exactly one stable version and zero or more explicitly named prerelease channels. It never contains URLs and never infers a version from Job numbers, timestamps, filenames, lexical ordering, or whichever build is newest.

Each selected version resolves to the immutable https://flog.run/releases/<version>/manifest.v1:

flog-release-v1
version	1.2.3
revision	0123456789abcdef0123456789abcdef01234567
artifact	darwin	amd64	<64-character-sha256>	<immutable-https-url>
artifact	darwin	arm64	<64-character-sha256>	<immutable-https-url>
artifact	linux	amd64	<64-character-sha256>	<immutable-https-url>
artifact	linux	arm64	<64-character-sha256>	<immutable-https-url>

Release manifests require all four supported targets, an exact semantic version, a full source commit, one unique artifact per target, and one SHA-256 checksum per artifact.

Rolling development builds use a separate flog-rolling-v1 contract at /releases/channels/unstable/rolling.v1. It identifies the fixed Flog product, rolling channel identity, Job #3, one exact Run, master source ref and full source SHA, canonical 0.0.0-dev.<12-character-SHA-prefix> version, and all four target archives with byte sizes, SHA-256 digests, and identity-pinned temporary Run URLs. /releases/channels/unstable/runs/<run>/rolling.v1 revalidates that same Run immediately before replacement. Rolling manifests are not Releases: they have no tag, version_url, lifecycle, or permanent artifact URL.

Installation safety#

The installer resolves a Release channel to an immutable version manifest, or selects one exact rolling Run. It downloads into a mode-0700 staging directory located inside the destination directory, verifies the archive's SHA-256 checksum, requires the exact archive entries BUILD-INFO.json, LICENSE, and flog, and streams only the flog entry into the staged executable. The final rename occurs on the same filesystem and is the only operation that replaces an existing installation. Rolling installs additionally verify the declared byte size and all BUILD-INFO.json identity fields, then refetch the exact-Run manifest. A newer Run becoming current cannot change the selected download; eviction, a new Release hold, or changed evidence makes the operation fail before replacement.

Network errors, redirects to disallowed protocols, malformed manifests, missing targets, checksum failures, malformed archives, interrupted downloads, and destination errors remove staging data and preserve an existing executable. Repeating the same version installation produces the same installed bytes.

Repopack Release adapter#

Job #3's automatic master Runs produce project-visible SHA-versioned development artifacts for rolling unstable; they do not create Releases or channel promotions. For a semantic release, manually run Job #1 from the exact full source SHA with an explicit version as documented in releases.md, then download its artifacts and verify SHA256SUMS.

Repopack Release is the sole authority for published versions, artifact URLs, visibility, lifecycle, and channel tips. The website reads only public distribution records for the fixed flog product in the flog project:

https://repopack.com/project/flog/releases/flog/channels/stable
https://repopack.com/project/flog/releases/flog/versions/<version>

flog.run maps those JSON records to the text protocol above. It validates the public/normal lifecycle, exact product and version identity, full source SHA, and exactly one archive for every supported target. Archive names, SHA-256 digests, sizes, and immutable HTTPS Release URLs must all match. SHA256SUMS and reviewed non-target metadata may coexist with the four archives; unexpected files that impersonate target archives are rejected. Archives remain hosted by Repopack and are never copied into the website.

Missing, private, deprecated, revoked, malformed, or unavailable records fail closed. Channel and exact-version responses use no-store, so promotion and revocation are not hidden by a long-lived website cache. Exact-version requests address the immutable Release version directly and therefore continue to work after a later stable promotion.

The rolling adapter likewise fails closed for a private, empty, stale, Release-held, evicted, malformed, or ambiguous Run. It anonymously reads only a public rolling listing and exact Run; the website contains no Repopack credential. The existing flog/unstable channel is intentionally still project-visible, so the production rolling endpoint remains unavailable until a separate operator-approved visibility rollout. Do not treat the examples below as a currently usable public feed.

Publishing and promoting#

Publishing a version, adding it to a channel, changing channel visibility, and promoting its tip are separate authorized release operations. They are not performed by the website, installer, build Job, or ordinary application deployment. The permanent flog product and empty project-visible stable channel already exist. After verifying the semantic Job Run, use the guarded Repopack Release workflow:

rp release prepare flog "$version" --job 1 --run "$run"
rp release publish flog "$version" --job 1 --run "$run"
rp release channel add flog stable "$version"
rp release channel show flog stable
# First public release only; later releases verify that it remains public:
rp release channel update flog stable --visibility public
rp release promote flog "$version" --channel stable
rp release channel show flog stable
rp release channel members flog stable

Every published Release starts unattached and project-only. Explicit channel membership is required before promotion, and a Release is publicly downloadable only while it belongs to a public channel. The visibility update is required once for the first public release; later releases must verify that channel show still reports public visibility before promotion. Do not remove older stable members after promotion: their continued membership is what keeps FLOG_VERSION and flog update --version working for historical versions. Use --attach during publication only when an existing canonical refs/tags/releases/flog/<version> tag already points to the exact source and matches the prepared Release.

All membership, visibility, and tip mutations require guarded browser confirmation. Do not perform them as an incidental part of a code or deployment task. A successful Job Run or published but unattached Release never changes the installer-visible stable version. Default installation continues to select the public immutable stable Release and never falls back to a development Run.

SHA-256 protects downloaded bytes against corruption and substitution relative to the HTTPS adapter response. Release-manifest signing and offline key management are tracked separately; until that is implemented, HTTPS integrity and controlled, reviewed channel promotion remain mandatory. Flog task #20 tracks signing and offline key management.

Self-update#

An installed POSIX release can update itself through the same manifests and artifact checks as the installer:

flog update
flog update --channel unstable
flog update --channel stable
flog update --channel next
flog update --version 1.2.3

The default is stable. --channel unstable opts into one temporary rolling Run for that invocation; channel choice is not persisted as a future default. --channel stable deliberately returns a development build to the current immutable stable Release, even when that cross-kind move is not a SemVer upgrade. Other immutable Release channels retain the existing no-regression and no-equal-precedence rules. --version remains Release-only and can select one exact stable, prerelease, or historical Release; it never addresses a historical rolling Run.

Rolling repeat detection records the installed channel/Run/source identity and binary digest in flog.update-state beside the executable. The state records identity only, not a preferred channel, and is removed by a stable or exact Release installation. Missing or inconsistent state causes conservative exact Run verification rather than treating equal SemVer precedence as equality.

--releases-url selects a compatible manifest mirror. The equivalent environment controls are FLOG_CHANNEL, FLOG_VERSION, and FLOG_RELEASES_URL; command-line selection options override channel/version environment values. FLOG_ALLOW_HTTP=1 exists only for isolated local fixtures and must not be used in production.

Self-update supports the same Linux/macOS amd64/arm64 matrix as the installer. It verifies strict channel and immutable release manifests, redirect protocols, the archive SHA-256, exact archive entries, and BUILD-INFO.json before writing a staged executable beside the running binary. A same-directory rename is the only replacement operation. Network, validation, checksum, archive, staging, permission, interruption, and rename failures leave the previous executable in place. The command never invokes sudo, changes profiles, or chooses another installation path; a non-writable executable directory produces an actionable error.

Flog 0.1.8 predates the rolling protocol and cannot bootstrap with flog update --channel unstable. Before public rollout, the initial compatible client must be installed from a reviewed immutable stable Release (or a separately verified exact development archive in a test environment). Only then can an operator explicitly select unstable after its public feed is approved.