Stoffel CLI Overview - Stoffel Documentation

The stoffel CLI is the entry point for building with Stoffel. Use it to create projects, check source, build bytecode, run clear checks, and exercise local MPC development flows.

curl -fsSL https://get.stoffelmpc.com | sh

The installer writes stoffel to ~/.local/bin by default. Add it to your path if your shell does not find it:

export PATH="$HOME/.local/bin:$PATH"

Check the available commands:

stoffel --help

Commands

Command	Alias	Purpose
`init`	`new`	Create a new Stoffel project from a template.
`check`		Validate source and project MPC settings without writing bytecode.
`compile`		Write compiled bytecode for a project or source file; can also disassemble `.stflb`.
`build`		Build project bytecode under `target/`.
`run`	`exec`, `execute`	Run a project directory, `.stfl` source file, or `.stflb` bytecode file.
`dev`		Watch a project and rerun it on local MPC when files change.
`test`		Run no-argument Stoffel test functions.
`status`	`doctor`	Show project health and environment status.
`clean`		Remove generated build artifacts.
`update`	`upgrade`	Check or update the CLI and project dependencies.

Create a project

stoffel init hello-mpc
cd hello-mpc

Choose the template that matches your build path:

stoffel init hello-mpc                         # default Stoffel/Rust project
stoffel init my-lib --lib                      # library-style Stoffel project
stoffel init rust-app --template rust
stoffel init py-app --template python
stoffel init contract-app --template solidity-foundry
stoffel init hardhat-app --template solidity-hardhat

--force writes template files into an existing directory without deleting unrelated files.

Project structure

The default template currently creates:

hello-mpc/
├── Cargo.toml
├── README.md
├── Stoffel.toml
└── src/
    ├── main.rs
    ├── main.stfl
    └── stoffel_bindings.rs

Stoffel.toml records package, MPC, and build settings:

[package]
name = "hello-mpc"
version = "0.1.0"

[mpc]
backend = "honeybadger"
parties = 5
threshold = 1

[build]
source = "src/main.stfl"
target_dir = "target"

backend selects the MPC backend recorded in generated bytecode:

Value	Use when
`honeybadger`	You want the default field-arithmetic MPC backend.
`avss`	You want AVSS with the default curve.
`avss:<curve>`	You want AVSS over a specific curve, for example `avss:secp256k1`.

For AVSS, you can also keep backend = "avss" and set curve = "ed25519", curve = "secp256k1", or another supported curve in the [mpc] table. See MPC Protocols for backend selection guidance.

Check source

Validate source and MPC settings without writing bytecode:

stoffel check

Use this before committing or before a longer local MPC run.

Compile bytecode

Compile a project or source file to Stoffel bytecode:

stoffel compile
stoffel compile src/main.stfl --output target/debug/hello-mpc.stflb
stoffel compile -O2 --backend honeybadger --parties 5 --threshold 1
stoffel compile -O2 --backend avss --field secp256k1 --parties 5 --threshold 1

Disassemble an existing bytecode file:

stoffel compile --disassemble target/debug/hello-mpc.stflb

Useful compile flags:

--output / --out: write to a specific .stflb file when compiling one source file.
--print-ir: print compiler intermediate representation.
-O, --opt-level: set optimization level, for example -O3.
--optimize: use O2 unless --release selects O3.
--release: write under target/release and use O3 unless overridden.
--backend, --field, --parties, --threshold, --instance-id: override project MPC settings for this compile. Use --backend honeybadger for the default field-MPC backend, or --backend avss --field <curve> / --backend avss:<curve> for AVSS.

Build a project

build writes bytecode under target/ using project settings:

stoffel build
stoffel build --release
stoffel build -O2

Run source or bytecode

Run the current project:

stoffel run

Run a specific file:

stoffel run --program-info
stoffel run target/debug/hello-mpc.stflb --entry main

Useful run flags:

--entry: function to execute; defaults to main.
--input NAME=VALUE: named function argument, repeat once per argument.
--input-file FILE: load named inputs from .json, .csv, or .txt.
--client-input SLOT=VALUE: local ClientStore input for programs that call ClientStore.take_share.
--client-input-file FILE: load ClientStore inputs from .json, .csv, or .txt.
--expected-output-clients N: declare local output-capable client slots 0..N-1.
--local: run on the local MPC test network; this is the default unless --network or --config is set.
--network --config FILE: connect to an MPC network described by a network/off-chain client TOML file.
--program-info: print function and instruction metadata before executing.
--timeout-secs N: local MPC timeout; defaults to 180 seconds.

Local MPC development

Run the project once through the local MPC test network:

cd /path/to/hello-mpc
stoffel dev \
  --parties 5 \
  --threshold 1 \
  --once

Run in watch mode by omitting --once:

stoffel dev \
  --parties 5 \
  --threshold 1

stoffel dev watches Stoffel.toml and the configured source tree, rebuilds, and reruns when a .stfl file or project config changes. Use --poll-ms to tune reload latency.

Rust wrapper

The default Rust template includes src/main.rs as an application wrapper. It imports stoffel::prelude::*, loads the generated binding metadata, compiles or loads the project program, sets local MPC topology with parties and threshold, and calls .execute_local().await? for local MPC testing. For application-style examples, prefer building bytecode with stoffel build and loading the resulting .stflb from Rust with Stoffel::load_file("target/debug/<project>.stflb")?.

Template status

The Rust SDK path is the primary application workflow. Python and Solidity templates are useful for integration planning; use their generated README files and the current repository when validating a deployment.

Troubleshooting

The command accepts an option but my generated project fails

Check the generated README.md and src/main.stfl. Template programs vary: some expect named function inputs with --input, while ClientStore examples expect local client inputs with --client-input.

I need exact current flags

Use command-specific help:

stoffel init --help
stoffel compile --help
stoffel run --help
stoffel dev --help

​Commands

​Create a project

​Project structure

​Check source

​Compile bytecode

​Build a project

​Run source or bytecode

​Local MPC development

​Rust wrapper

​Template status

​Troubleshooting

​The command accepts an option but my generated project fails

​I need exact current flags