Installing yidam
The yidam binary is the whole toolchain. There is no daemon, no service, and nothing to
configure before the first run — a derived repository records which yidam governs it in its
own .yidam.toml, and the binary reads that.
Six channels serve the same artifact. Each one is exercised weekly by
install-channels.yml,
which runs the lines below verbatim in a container holding only the tools the line claims to
need and asserts that yidam --version answers with the latest release. A channel that stops
working turns that job red, so a line documented here is a line somebody checked this week.
The install script
curl -fsSL https://raw.githubusercontent.com/goedelsoup/yidam/main/install.sh | sh
Resolves the newest cli/v* release for your platform, downloads the tarball and its
.sha256, verifies it, and installs to ~/.local/bin. If neither shasum nor sha256sum
is present it refuses the install rather than trusting an unverified download — that is a
deliberate failure, not a fallback. It warns if the install directory is not on your PATH.
| Variable | Effect |
|---|---|
YIDAM_BIN_DIR | Install somewhere other than ~/.local/bin |
YIDAM_VERSION | Install a specific tag instead of the latest — e.g. cli/v0.4.0 |
YIDAM_REPO | Resolve releases from a fork instead of goedelsoup/yidam |
GITHUB_TOKEN | Optional. Raises the rate limit on the release lookup — see below |
YIDAM_API | Point the release lookup at a GitHub Enterprise host |
If the install fails with a rate-limit error. The script asks the GitHub API which
release is newest. That call is anonymous. GitHub allows 60 anonymous calls an hour, per IP
address. Behind a shared address, that allowance belongs to everyone on it. So the call can
be refused with HTTP 403. The script tells you when this has happened, and when the limit
resets. Set GITHUB_TOKEN to any token you hold, and the limit rises. Or set
YIDAM_VERSION to a tag, and the lookup is skipped.
Homebrew
brew install goedelsoup/tap/yidam
macOS and Linux. The formula is rendered from the release's own checksums by the release
workflow, so the tap cannot lag a published version, and brew upgrade carries yidam along
with everything else.
mise
mise use -g "github:goedelsoup/yidam[version_prefix=cli/v]@latest"
The github: backend downloads the
same release tarball the script does, verifies the published .sha256, and resolves the
binary inside the extracted directory. -g installs it globally; drop it to pin yidam in one
project's mise.toml. Either way the line writes:
[tools]
"github:goedelsoup/yidam" = { version = "latest", version_prefix = "cli/v" }
version_prefix is load-bearing, and leaving it out does not get you a slightly wrong
version — it fails outright. This repository publishes four layers onto one release list
(see versioning), so a resolver that does not filter by tag prefix asks the
repository-wide question:
Without version_prefix | What happens |
|---|---|
github:goedelsoup/yidam@latest | resolves editor/v* — No matching asset found for platform, because that release ships only a .vsix |
github:goedelsoup/yidam@0.6.0 | 404 on releases/tags/goedelsoup/yidam@0.6.0 |
Not ubi:. mise 2026.7.0 warns that backend is deprecated and removed in 2027.1.0.
tag_regex is not a github: backend option — mise accepts it in silence and then fails
exactly as the table above does. version_prefix is the one that works.
cargo-binstall
cargo binstall yidam
Fetches the same prebuilt artifact the script does — it does not compile. Useful when cargo is already on hand and you would rather not add another package manager.
Claude Desktop, as a bundle
Not a channel that installs a binary you run — it installs one Claude Desktop runs, without a
terminal anywhere in the process. Download the .mcpb for your Mac from the
latest release and drag it onto the Extensions
pane, or:
open yidam-0.25.0-aarch64-apple-darwin.mcpb # Apple silicon
open yidam-0.25.0-x86_64-apple-darwin.mcpb # Intel
The bundle is a zip holding a manifest and the light yidam build, and the installer asks
which repository to serve — so nothing lands on your PATH and no client configuration is
written by hand. macOS only: Claude Desktop runs there and on Windows, and this project
cross-compiles no Windows target.
It gives you the MCP server and nothing else. If you want to run yidam — lint, status,
propose — you want one of the channels above as well. Connecting an
agent has the rest.
From source
cargo install --git https://github.com/goedelsoup/yidam --tag cli/v0.25.0 --locked yidam
The default build needs only a Rust toolchain: no system C library, no ML runtime. --locked builds from the lock file the tag committed, which is what makes this the
same binary the release was built from; without it cargo re-resolves every dependency and you
get something that merely resembles it.
yidam is also on crates.io, so cargo install yidam works
— but it re-resolves dependencies the same way, and pinning the tag is the reproducible form.
MSRV is Rust 1.88, which is the toolchain this repository pins. It read 1.85 here and in
Cargo.toml while every gate built 1.88 and nothing compiled the floor — an unverified promise
rather than a lower one — so #463 raised it to the pin, where every build verifies it.
Verify the install
$ yidam --version
yidam <version> (<commit>) [reports vector-read index export-graph tonpa serve-http vault-s3 s3-vectors catalog-fetch pdf-text github-app]
Three facts, and the third is the one that matters: the version, the commit it was built from,
and the features compiled into it. The version and commit are redacted; yours are whatever
you installed. The feature list is not an example. It is the default set, which is what every
released artifact carries. A command that is absent from a build is absent because
of that list, so it is printed on every --version rather than left to be discovered when a
subcommand reports unrecognized subcommand.
Inside a derived repository, yidam doctor is the fuller check — it
answers whether the running binary is the one the repository pins, whether .yidam/bin is
ahead on PATH, and how stale the vendored prelude is.
Check which build you have
The binary is partitioned by cargo feature so the common case stays cheap to install. Released artifacts — the script, the tap, binstall — carry the default set.
| Feature | Adds | Build cost |
|---|---|---|
reports (default) | Every pure-Rust command: reports, gates, queries, clone, overlay, serve --mcp, serve --lsp, export to graphml/llms | None |
tonpa (default) | Bundle dependency manager — tonpa add, verify, update | reqwest (rustls) + tokio; vendored C, no system library |
vector-read (default) | index-build, and upgrades serve --mcp's retrieve from keyword to semantic | fastembed and ONNX Runtime. +78 packages, +32.6 MB — the largest cost in the default set. On an Intel Mac the runtime is loaded at run time rather than linked (see below) |
index | An alias for vector-read, kept so existing --features index installs still build | Same as vector-read |
export-sqlite | export --format sqlite | Bundled SQLite + sqlite-vec, compiled from C |
vault-s3 (default) | The s3:// transport for yidam vault. The rest of the vault — addressing, cache, file:// — is ungated | hmac + reqwest (rustls) + tokio |
s3-vectors (default) | The S3 Vectors transport — index-push, and answering retrieve out of a vector bucket instead of a local index. Everything that decides what would be sent is ungated | +0 packages; hmac, reqwest and tokio are already here for vault-s3 |
export-graph (default) | export --format rdf | Pure Rust |
serve-http (default) | serve --mcp --http — MCP over a URL, the transport every remote agent platform needs | hyper 1.x server features. +1 package (httpdate); hyper is already here for reqwest |
catalog-fetch (default) | catalog-fetch against a url or url_template location. The kind: file path — and everything that decides what would be fetched — is ungated | +0 packages; reqwest and tokio are already here for tonpa and vault-s3 |
pdf-text (default) | catalog-extract taking a text reading of a PDF artifact. Lint compares a quotation with a recorded reading in every build | +35 packages, +1.4 MB, all pure Rust |
github-app (default) | cluster land --git-auth github-app — the lander mints a short-lived GitHub App installation token instead of pushing with a deploy key. Every check on the remote, the API URL and the flags is ungated | +0 packages; ring and base64 are already here through reqwest's rustls |
calculators-gluon | The typed calculator arm (RFC-0042) — a calculator whose entry point is typechecked Corpus -> Computed, so the executor can decline it before it runs. Declared as run = { gluon = "…" }; a build without it parses the declaration and declines the step by name | +71 packages, +6.8 MB. The largest cost in this table, and the reason this one is not in the default set |
source-transforms | A source pack's describe and extract transforms (RFC-0048), run in the calculator arm's closed prelude over a JSON, XML or CSV response the host parses. Implies calculators-gluon. A build without it checks the rest of a pack, drafts an entry from the pack's templates and names the fields it could not fill | +3 packages, +0.12 MB over calculators-gluon |
full | All of the above |
Two things follow from that table that are easy to get backwards.
Deriving a repository does not need full. clone, overlay, tonpa, both serve
transports, every report and every gate are in the default set. A --no-default-features
binary still serves MCP; what it does not serve is semantic retrieval, and it says so on every
call rather than silently returning keyword results as though they were embeddings.
Reading an index and building one are the same build. Building one used to need
--features index, which added LanceDB and needed protoc 31. Nothing ever read the LanceDB
table, so it was removed, and index-build now writes the corpus.arrow every reader decodes.
Measured against this repository's lockfile with cargo tree: without vector-read the default
set resolves 215 packages, with it 293, and the old index set resolved 616.
vector-read is a default even though it more than doubles the binary (23 MB to 56 MB on
aarch64 macOS), because an install that cannot build or read an index cannot do the retrieval
the rest of the toolchain is built to feed. fastembed is taken without its OpenSSL and image
defaults, and ONNX Runtime arrives as a prebuilt static library on every released target but
one: ort publishes none for Intel macOS, so there yidam loads libonnxruntime.dylib
(1.24 or newer) when a command first needs a model. brew install onnxruntime provides it, or
point ORT_DYLIB_PATH at one. Every command that does not embed runs without it. Whether you
have semantic retrieval is on yidam --version and in yidam doctor.
The Linux release binaries need glibc 2.39 or newer. ONNX Runtime's prebuilt requires it. That covers Debian 13 and Ubuntu 24.04. Debian 12, Ubuntu 22.04 and RHEL 9 are older. On those, install from source with the command below, which leaves the runtime out.
tonpa is a default even though it costs an HTTP stack, because it is the only feature
whose absence broke an instruction rather than removing a capability. Without it
yidam tonpa add … answered unrecognized subcommand, and inside a script with output
redirected that is indistinguishable from success.
To build a different set from source:
# The default set less the embedding model: no ONNX Runtime, keyword retrieval only.
cargo install --git https://github.com/goedelsoup/yidam --tag cli/v0.25.0 --locked \
--no-default-features \
--features reports,tonpa,vault-s3,s3-vectors,export-graph,serve-http,catalog-fetch,pdf-text,github-app \
yidam
# Everything, including the SQLite export and the gluon calculators.
cargo install --git https://github.com/goedelsoup/yidam --tag cli/v0.25.0 --locked \
--features full yidam
--features full requires a C toolchain on the build machine. That is the
maintainer's build — see Contributing, where mise install provisions all
of it.
Upgrade
Whichever channel installed it:
brew upgrade yidam # tap
cargo binstall yidam # binstall — re-run, it replaces
curl -fsSL …/install.sh | sh # script — re-run, it overwrites
A derived repository pins a template commit, not a CLI version, so upgrading the binary does
not by itself change what any repository inherits. mise run yidam-vendor-update is the
separate act that adopts a newer prelude; see Versioning and releases for why
those are different layers with different lifetimes.
Uninstall
rm ~/.local/bin/yidam # script (or "$YIDAM_BIN_DIR/yidam")
brew uninstall yidam # tap
cargo uninstall yidam # cargo install / binstall
Nothing is installed outside that binary. A derived repository's .yidam/ is its own content
and is unaffected.