Installation

Sema ships as a single self-contained runtime — the sema command — built from its Rust reference implementation. This page builds it from source, which works everywhere Rust does, and runs an example to confirm the toolchain is live.

This is a reference implementation

Sema is a working reference implementation built from source: a tree-walking interpreter (the reference semantics), an opt-in bytecode VM, a CLI, an LSP, and — behind a feature flag — native model backends. The default build has no machine-learning dependency and is fast and portable; the model backends are a separate, larger build. What follows is the honest, works-today path.

Prerequisites

• The Rust toolchain. Install it from rustup.rs. Cargo (Rust’s build tool) comes with it. That is the only hard requirement for the default build.
• Optional, for the real model backends: a working GPU/CPU compute stack. The real-model feature links the candle backend (Metal on macOS, CUDA or CPU elsewhere). Building it is heavier and, on first use, it downloads model weights.

Build from source

Clone the repository and build the release binary from the sema/ directory:

git clone https://github.com/Xpitfire/sema
cd sema
cargo build --release

The CLI lands at target/release/sema. The default build is deliberately ML-free, so ~=, the semantic operations, and simulate run on built-in deterministic engines (a hash embedder and an extractive summarizer). That is enough to write, check, run, and verify real Sema programs — the results are reproducible, which is exactly what you want while learning and testing.

Optional: the native model backends

To link the real local model backends (generation via GGUF, embeddings, and the vision/speech capabilities), build with the feature flag:

cargo build --release --features real-model

This downloads models

The real-model build is larger, and the first run of a model-backed capability downloads model weights from Hugging Face. Do this deliberately, with network access, not inside a locked-down sandbox. You do not need it to follow the rest of the Start-Here section — the default build runs everything on its deterministic engines.

Put sema on your PATH

The binary is standalone; put it somewhere on your PATH so you can invoke it as sema from anywhere. For example, into a directory that is already on your PATH:

cp target/release/sema ~/.local/bin/sema      # or another PATH directory

Alternatively, run it in place with its full path (./target/release/sema …) or via Cargo (cargo run --release -p sema-cli -- …). The rest of the docs assume plain sema.

Verify the install

Check the version and open the interactive console:

sema --version          # prints: sema <version>
sema repl               # interactive console — Ctrl-D or :quit to leave

sema --version confirms the binary is on your PATH and runnable. sema repl drops you into an interactive session where you can evaluate expressions and inspect definitions.

Running sema with no arguments prints the full command list:

usage: sema <tokens|parse|check|run|circuit|debug|infer|doc|assure|repl|dap|add|remove|list|lsp> <args>

Run your first example

The repository ships a corpus of runnable example projects under examples/. Each is a directory with a src/ folder and (usually) a sema.toml manifest. Run one from the repository root:

sema run examples/polymorphism

polymorphism is deterministic — it makes no model calls — so it produces the same output every time and needs neither network nor the real-model build. It exercises the trait/struct/enum system end to end. You can browse the other projects the same way:

sema run examples/research-agent      # a small agent pipeline on the stdlib
sema run examples/graphrag            # add SEMA_VM=1 to run on the bytecode VM

To statically check a project without executing it — the command you will run after every edit — point sema check at the project directory:

sema check examples/polymorphism

If sema run examples/polymorphism prints its summary line and sema check reports no diagnostics, your toolchain is working.

Installing packages

Sema has a package manager for both ecosystems. sema add installs a PyPI package into a project-local environment (.sema/venv, via uv with a pip fallback), immediately usable from Sema; it also installs native Sema packages from a local path or a git+<url> source:

sema add numpy                        # a PyPI package, usable natively from Sema
sema add ./greetings                  # a local native Sema package
sema list                             # what's installed

The standard library needs no installation — it ships embedded in the compiler and imports everywhere as from std.<module> import …. See Project Layout for how manifests and dependencies fit together.

Next

• Your First Program — write, check, and run a project of your own in ten minutes.
• Toolchain — a complete reference for every sema command.