Skip to content

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.

VariableEffect
YIDAM_BIN_DIRInstall somewhere other than ~/.local/bin
YIDAM_VERSIONInstall a specific tag instead of the latest — e.g. cli/v0.4.0
YIDAM_REPOResolve releases from a fork instead of goedelsoup/yidam
GITHUB_TOKENOptional. Raises the rate limit on the release lookup — see below
YIDAM_APIPoint 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_prefixWhat happens
github:goedelsoup/yidam@latestresolves editor/v* — No matching asset found for platform, because that release ships only a .vsix
github:goedelsoup/yidam@0.6.0404 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.

FeatureAddsBuild cost
reports (default)Every pure-Rust command: reports, gates, queries, clone, overlay, serve --mcp, serve --lsp, export to graphml/llmsNone
tonpa (default)Bundle dependency manager — tonpa add, verify, updatereqwest (rustls) + tokio; vendored C, no system library
vector-read (default)index-build, and upgrades serve --mcp's retrieve from keyword to semanticfastembed 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)
indexAn alias for vector-read, kept so existing --features index installs still buildSame as vector-read
export-sqliteexport --format sqliteBundled SQLite + sqlite-vec, compiled from C
vault-s3 (default)The s3:// transport for yidam vault. The rest of the vault — addressing, cache, file:// — is ungatedhmac + 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 rdfPure Rust
serve-http (default)serve --mcp --http — MCP over a URL, the transport every remote agent platform needshyper 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-gluonThe 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-transformsA 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
fullAll 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.