Skip to content

Getting started

The binary release contract supports three Linux and macOS targets. Every published archive must be checksum-bound, signed, and accompanied by an artifact SBOM and provenance. Follow the independent verification procedure before installing a downloaded binary. Rust is required only when building from source, and ffprobe is optional for stream-level media metadata.

The currently published v0.1.1 bundle targets source revision b82599a2231e997d42fd9f26f4b59587f4ae14cf. A build from current main can contain later read-only features; preserve its exact source revision when comparing behavior with the release.

The release passed native pilot qualification on all three supported targets and independent bundle verification. Use the pilot operator guide for separate local state, a first scan without probing, private report handling, and interruption, reconnect, upgrade, and rollback procedures.

Install a verified prebuilt binary

First complete the independent verification procedure. It leaves the verified platform archives under optiflow-release/. Select exactly one supported target:

  • x86_64-unknown-linux-gnu
  • x86_64-apple-darwin
  • aarch64-apple-darwin

Then extract that archive, copy the binary into a user-owned executable directory, and run the read-only environment check:

release_version="v0.1.1"
release_target="x86_64-unknown-linux-gnu"
unpack_directory="optiflow-${release_version}-${release_target}"

mkdir -p "${unpack_directory}" "${HOME}/.local/bin"
tar --extract --gzip \
  --file "optiflow-release/optiflow-${release_version}-${release_target}.tar.gz" \
  --directory "${unpack_directory}"
cp "${unpack_directory}/optiflow" "${HOME}/.local/bin/optiflow"
chmod 0755 "${HOME}/.local/bin/optiflow"
"${HOME}/.local/bin/optiflow" doctor

Choose the target that exactly matches the current host. The release does not claim support for other architectures or libc variants.

Build from source

git clone "https://github.com/egohygiene/optiflow.git"
cd "optiflow"
cargo build --locked --release

The release binary is written to target/release/optiflow.

Inspect the environment

./target/release/optiflow doctor

doctor reports the local state location and optional capability availability. It does not modify source media.

Run a first scan

Start with a directory you control:

./target/release/optiflow scan "/path/to/Media"

The command prints a run identifier and commits immutable evidence beneath the local state directory:

runs/<run-id>/
├── effective-policy.json
├── run.json
└── report.json

In v0.1.1, the default probe policy and an available ffprobe allow report v6 to include read-only lossless-PNG profile evidence. That capability is not present in the earlier v0.1.0 binary. Pass --no-probe to record that this analysis was not requested. See media-profile evidence before interpreting a review candidate; it is not an output or savings guarantee.

Generate a review-only plan

./target/release/optiflow plan exact-duplicates \
  --run "<run-id>"

The generated plan declares "mutates_files": false. Its proposed keep path is a deterministic review default, not a claim that one copy is objectively better.

Use machine output

./target/release/optiflow \
  --output-format "json" \
  scan "/path/to/Media"

JSON owns standard output in machine mode. Diagnostics use the typed command result instead of contaminating the JSON stream. See the CLI outcome contract before automating on exit codes or result fields.

Next steps