Stoffel CLI App Workflow

Scope: AI-agent-agnostic playbook for building applications with the Stoffel framework. This is not a maintainer guide for compiler, VM, protocol, or release engineering work. Dependency assumption: generated applications use current public crates.io releases by default. A pinned official GitHub revision is the fallback; a local path is explicit, nonportable framework-development mode only.

Use when

Use this playbook when building, running, testing, inspecting, or troubleshooting a Stoffel application through the stoffel command.

Current source of truth

crates/stoffel-cli/src/main.rs
crates/stoffel-cli/src/project.rs
crates/stoffel-cli/tests/cli.rs
crates/stoffel-rust-sdk/src/input_file.rs

Core commands

stoffel init my-app          # alias: stoffel new my-app
stoffel status --verbose     # alias: stoffel doctor --verbose
stoffel check                # validate source and project MPC settings
stoffel build                # build bytecode under target/debug/
stoffel build --release      # build bytecode under target/release/ and default to O3
stoffel compile src/main.stfl --output target/debug/app.stflb
stoffel compile --disassemble target/debug/app.stflb
stoffel run                  # local MPC testing by default unless --network/--config is set
stoffel dev --once           # one build+run pass; omit --once for watch mode
stoffel test --verbose       # run no-argument Stoffel test functions
stoffel clean --dry-run
stoffel update --check       # alias: stoffel upgrade --check

stoffel run, build, and compile accept a project directory, source directory, single .stfl file, or existing .stflb depending on the command. build.source may point at either a file or a source directory; when it is a directory, the CLI recursively compiles all src/**/*.stfl files.

Project config shape

A typical app has Stoffel.toml:

[package]
name = "my-app"
version = "1.0.0" # your app package version
authors = []

[mpc]
backend = "honeybadger"
parties = 5
threshold = 1
# instance_id = 0
# curve = "bls12_381"       # optional alias: field; mainly for AVSS backend

[build]
source = "src/main.stfl"    # or "src" for a source directory
target_dir = "target"       # alias: output_dir
# optimization_level = 2

Rules enforced by the CLI:

[package].name and [package].version must be non-empty.
package.name may use only letters, numbers, -, and _.
build.source must be a relative .stfl file path or a relative source directory inside the app.
build.target_dir must be a relative directory inside the app and cannot be under src/.
optimization_level must be 0..3.
parties, threshold, and instance_id must be unquoted positive whole numbers.
HoneyBadger requires Byzantine topology: at least 4 * threshold + 1 parties, with the current default of 5 parties and threshold 1.

Backend and curve flags

Project config and CLI overrides support:

stoffel check --backend honeybadger --parties 5 --threshold 1
stoffel build --backend avss:bls12_381
stoffel build --backend avss:bn254
stoffel build --backend avss:curve25519
stoffel build --backend avss:ed25519
stoffel build --backend avss:secp256k1
stoffel build --backend avss:p-256

--protocol aliases --backend; --curve aliases --field in CLI parsing. HoneyBadger does not take a curve suffix.

App templates

Use stoffel init --help for current template names. Current app-facing templates include:

stoffel init my-app                         # default Stoffel app + Rust wrapper files
stoffel init my-lib --lib                   # library-style Stoffel source
stoffel init my-rust-app --template rust    # Rust app wrapper with nested stoffel/ project
stoffel init my-python-app --template python
stoffel init my-foundry-app --template solidity-foundry
stoffel init my-hardhat-app --template solidity-hardhat

Treat non-Rust wrapper templates as integration scaffolds; use the Rust SDK for executable application flows.

Audit generated Rust apps

Immediately inspect every generated Cargo.toml; do not assume the CLI binary that generated it came from the same release as these docs. The portable default follows the versions on the current Rust SDK installation page:

[dependencies]
stoffel = { package = "stoffel-rust-sdk", version = "<current-docs-version>" }

[build-dependencies]
stoffel-bindgen = "<current-docs-version>"

If a required fix is not published, pin both Stoffel crates to the official repository and a full 40-character revision. Keep them on the same revision:

[dependencies]
stoffel = { package = "stoffel-rust-sdk", git = "https://github.com/Stoffel-Labs/stoffel.git", rev = "<full-40-character-commit-sha>" }

[build-dependencies]
stoffel-bindgen = { git = "https://github.com/Stoffel-Labs/stoffel.git", rev = "<full-40-character-commit-sha>" }

An adjacent path such as path = "../stoffel/crates/stoffel-rust-sdk" is allowed only when a framework contributor explicitly selects nonportable local-checkout mode. It must not appear in a generated app intended for another user or repository. Generated binary applications must include and commit Cargo.lock. After auditing Cargo.toml, regenerate the lockfile and use it for every check:

APP_MANIFEST="/absolute/path/to/generated-app/Cargo.toml"
cargo generate-lockfile --manifest-path "$APP_MANIFEST"
cargo check --locked --manifest-path "$APP_MANIFEST"
cargo test --locked --manifest-path "$APP_MANIFEST"
cargo metadata --locked --format-version 1 --manifest-path "$APP_MANIFEST" \
  > "${APP_MANIFEST%/*}/cargo-metadata.json"

Audit cargo-metadata.json, not only manifest text. Each Stoffel package’s source must be registry+... or the pinned official git+https://github.com/Stoffel-Labs/stoffel.git?...#<full-sha>. A null source identifies a path/workspace package and fails the portable-app check. Prove portability from a clean external checkout with no sibling Stoffel repository:

PROOF_DIR="$(mktemp -d)"
APP_COMMIT="<reviewed-app-commit-sha>"
git clone "<generated-app-repository-url>" "$PROOF_DIR/app"
git -C "$PROOF_DIR/app" checkout --detach "$APP_COMMIT"
cargo check --locked --manifest-path "$PROOF_DIR/app/Cargo.toml"

Repository scripts must derive their root from the script file; callers may invoke them from any directory:

SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
APP_ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel)"
STOFFEL_ROOT="$APP_ROOT"
if [ ! -f "$STOFFEL_ROOT/Stoffel.toml" ] && [ -f "$APP_ROOT/stoffel/Stoffel.toml" ]; then
  STOFFEL_ROOT="$APP_ROOT/stoffel"
fi
test -f "$STOFFEL_ROOT/Stoffel.toml"
stoffel check "$STOFFEL_ROOT"
cargo check --locked --manifest-path "$APP_ROOT/Cargo.toml"

Inputs

Named function inputs use repeated --input flags:

stoffel run src/main.stfl --input a=40 --input b=2

ClientStore inputs use repeated --client-input flags. Repeating the same slot appends values in order for that client:

stoffel run examples/mpc_top_k/main.stfl \
  --client-input 0=50 --client-input 0=20 --client-input 0=40 \
  --client-input 0=10 --client-input 0=30 \
  --expected-output-clients 1

Do not pass comma-separated assignments like --input a=1,b=2.

Input files

Both named inputs and ClientStore inputs can be loaded from .json, .csv, or .txt. Named inputs:

stoffel run --input-file inputs.json
stoffel run --input-file inputs.csv
stoffel run --input-file inputs.txt

Formats:

{"a": 40, "b": 2}

a,b
40,2

# one name=value per line
a=40
b=2

ClientStore inputs:

stoffel run --client-input-file client-inputs.json --expected-output-clients 1
stoffel run --client-input-file client-inputs.csv --expected-output-clients 1
stoffel run --client-input-file client-inputs.txt --expected-output-clients 1

Formats:

{"0": [40, 2], "1": [7]}

slot,value
0,40
0,2
1,7

# repeated slots append in order
0=40
0=2
1=7

Values may be integers, unsigned integers where supported, booleans, strings, JSON arrays/objects, or 0x-prefixed bytes depending on the execution path.

Bytecode and inspection

stoffel build --program-info        # build stats are printed after bytecode write
stoffel run target/debug/app.stflb --program-info
stoffel compile --disassemble target/debug/app.stflb

--program-info on run prints function/instruction metadata and client IO metadata before execution.

Validation / done criteria

For a CLI workflow change or app setup, collect real output from:

stoffel status --verbose
stoffel check
stoffel build
stoffel run --timeout-secs 180

If tests exist:

stoffel test --verbose

For secret examples copied from the repository, use the exact first-line # run-args: header when present.

Common pitfalls

stoffel run --config expects network/off-chain config, not project Stoffel.toml.
stoffel init creates a project directory, not a single file.
Do not accept generated path = "../stoffel/..." dependencies as a portable default.
Do not use branch = "main", a tag, or an abbreviated Git SHA as the fallback; pin a full official revision.
Do not validate only from inside the Stoffel framework checkout, where workspace state can conceal dependency leaks.
Do not rely on cd app && ... in automation; pass explicit paths derived from the script or manifest.
If a path already contains Stoffel.toml, use stoffel status or stoffel run; do not re-init unless intentionally refreshing template files with --force.
Do not pass named inputs to ClientStore programs or ClientStore inputs to normal function-argument programs.
Do not claim a command works unless it was actually run.

Overview

App Development Skills

Use when

Current source of truth

Core commands

Project config shape

Backend and curve flags

App templates

Audit generated Rust apps

Inputs

Input files

Bytecode and inspection

Validation / done criteria

Common pitfalls

Next playbooks

​Use when

​Current source of truth

​Core commands

​Project config shape

​Backend and curve flags

​App templates

​Audit generated Rust apps

​Inputs

​Input files

​Bytecode and inspection

​Validation / done criteria

​Common pitfalls

​Next playbooks

Use when

Current source of truth

Core commands

Project config shape

Backend and curve flags

App templates

Audit generated Rust apps

Inputs

Input files

Bytecode and inspection

Validation / done criteria

Common pitfalls

Next playbooks