fherma

Command line interface for the FHERMA kernel catalogue.

pipx install fherma        # or: uv tool install fherma

A command line tool belongs in an environment of its own, and on macOS it has no choice: Homebrew marks its Python as externally managed, so pip install into it is refused. Inside a virtual environment pip install fherma is exactly right.

Either way that is the whole toolchain — fherma-lang comes with it as a dependency, so the install leaves two commands on the path: fherma, and fherma-lang for the language on its own. Check what you got:

$ fherma --version
fherma       0.2.1
fherma-lang  0.8.0
python       3.13.4

$ fherma doctor
✓ python       3.13.4
✓ fherma       0.2.1
✓ fherma-lang  0.8.0
✓ commands     auth, implementation, testing
✓ profile      default → https://api.fherma.io
• credentials  no token

doctor is offline by default — the usual reason to run it is that something is wrong, and a network timeout would bury the answer. Pass --online to check the token as well. It exits non-zero only when the toolchain is actually broken; a missing token is not broken, since scaffolding from a local signature never needs one.

Tab completion, once:

fherma completion zsh >> ~/.zshrc      # or bash, or fish

What it is for

A kernel in FHERMA is a computational problem; a specification is one precise statement of it. Before implementations can be submitted against a specification, it needs three functions — a generator, an oracle and a verifier — which say where test data comes from, what the right answer is, and how a verdict is reached.

This tool fetches the scaffold for those three, runs their checks locally, and sends them back. The other side — an implementation answering a specification — is scaffolded the same way, by fherma implementation init, in Python, C++ or Rust.

Getting started

fherma auth login
fherma testing init polymult/rlwe@1.0.0

That writes a bundle:

polymult-rlwe-1.0.0/
├── fherma.toml      generated — which specification this belongs to
├── fherma.py        generated — Point, Inputs, Outputs, Stream, Tensor
├── main.py          generated — the bundle's command line: make · verify · info
├── README.md        generated — the signature, and what to write
├── generate.py      yours
├── oracle.py        yours
├── verify.py        yours, and usually unnecessary
├── vectors/         worked examples, for accepting the oracle
└── assets/          data files the three functions may read

fherma.py is derived from the specification's signature: the types are already correct, so there is nothing to declare and nothing to get wrong. Write the two function bodies; the third is usually unnecessary, since most verdicts are exact equality and that is what the platform does when verify.py says nothing.

The generated files are rewritten by fherma testing init --update; yours never are. fherma testing inspect reads the three without running them, fherma testing run calls one in a child process with a time and memory limit, and fherma testing submit sends the bundle to the platform.

Commands

fherma auth            login · logout · whoami
fherma testing         init · status · inspect · run · submit
fherma implementation  init
fherma doctor          check the installation
fherma completion      a script for bash, zsh or fish

Name a specification as kernel/spec@version; the version may be left off, and the latest published one is used.

fherma testing init polymult/rlwe@1.0.0
fherma testing init polymult/rlwe --oracle --verifier    # two of the three
fherma testing init --signature ./sig.fhk                # no platform involved
fherma implementation init polymult/rlwe --lang cpp      # the answering side

The scaffold itself comes from fherma-lang and is built in this process, so the platform is asked for one thing — the signature — and --signature needs no network at all.

More arrive as the platform grows; fherma <group> --help lists what a group can do.

Every command takes --json, because this output is read by CI and by the web interface as well as by people. Exit codes are fixed: 0 success, 1 a check did not pass, 2 a usage error, 3 not authorised, 4 the platform could not be reached.

Profiles

fherma --profile staging auth login

Configuration lives in ~/.fherma/config.toml. FHERMA_URL and FHERMA_TOKEN override it, so continuous integration never has to write a token to disk.