> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stoffelmpc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Basic Usage

> Daily Stoffel CLI workflows for checking, building, running, testing, and debugging Stoffel projects.

This page describes the `stoffel` CLI. The `stoffel` binary is a Cargo-like project tool for creating, checking, building, running, and iterating on Stoffel apps. It is the developer-facing entry point for local MPC workflows.

## Core workflow

```bash theme={null}
stoffel init hello-mpc
cd hello-mpc
stoffel check
stoffel build
stoffel run
```

Use `stoffel --help` to see the installed command set. Current commands are:

* `init` / `new`: create a project from a template.
* `check`: validate source and MPC configuration without writing bytecode.
* `compile`: compile a project, source directory, or `.stfl` file to `.stflb` bytecode, or disassemble existing bytecode.
* `build`: build project bytecode under `target/`.
* `run`: run a project, `.stfl` source file, or `.stflb` bytecode through local or network MPC execution.
* `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 dependency files.

## Creating projects

```bash theme={null}
# Default Stoffel project
stoffel init my-project

# Supported templates
stoffel init py-app --template python
stoffel init rust-app --template rust
stoffel init foundry-app --template solidity-foundry
stoffel init hardhat-app --template solidity-hardhat

# Template aliases
stoffel init py-app --template py
stoffel init foundry-app --template foundry
stoffel init hardhat-app --template hardhat

# Library-style Stoffel project
stoffel init my-library --lib

# Refresh template files in an existing directory without deleting unrelated files
stoffel init . --force
```

`--lib` cannot be combined with `--template`. Use `stoffel init --help` for supported template names.

## Project structure

The default template currently creates a Rust-backed Stoffel project:

```text theme={null}
my-project/
├── Cargo.toml
├── README.md
├── Stoffel.toml
└── src/
    ├── main.rs
    ├── main.stfl
    └── stoffel_bindings.rs
```

Other templates place the Stoffel program under a nested `stoffel/` directory and include the host-language scaffold for Python, Rust, Foundry, or Hardhat.

## `Stoffel.toml`

`Stoffel.toml` is the project manifest. The CLI reads package, build, and MPC settings from this file. A minimal shape looks like:

```toml theme={null}
[package]
name = "my-project"
version = "0.1.0"

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

[mpc]
backend = "honeybadger"
curve = "bls12-381"
parties = 5
threshold = 1
```

Use command-line overrides while developing:

```bash theme={null}
stoffel check --backend honeybadger --field bls12-381 --parties 5 --threshold 1
stoffel build --release --parties 5 --threshold 1
stoffel run --parties 5 --threshold 1
```

Do not pass project `Stoffel.toml` to `stoffel run --config`. `--config` is for an MPC network/off-chain client TOML file; pass the project path as the positional `PATH` instead.

## Checking and compiling

```bash theme={null}
# Validate the current project without writing bytecode
stoffel check

# Validate a source file or directory
stoffel check src/main.stfl
stoffel check src

# Print compiler IR for debugging
stoffel check --print-ir

# Build bytecode under target/
stoffel build
stoffel build --release

# Compile a project, source directory, or single file
stoffel compile
stoffel compile src/main.stfl --output target/debug/main.stflb
stoffel compile src/main.stfl -O3 --output target/release/main.stflb

# Disassemble bytecode
stoffel compile --disassemble target/debug/my-project.stflb
```

Stoffel bytecode uses the `.stflb` extension.

Optimization flags accepted by `compile`, `build`, and source-compiling `run` include:

```bash theme={null}
stoffel build -O0
stoffel build -O 2
stoffel build --opt-level 3
stoffel build --optimize      # O2 unless --release selects O3
stoffel build --release       # writes under target/release
```

## Running programs

```bash theme={null}
# Run the current project through local MPC
stoffel run

# Run a source file or bytecode file
stoffel run src/main.stfl
stoffel run target/debug/my-project.stflb

# Select an entry function
stoffel run --entry main
stoffel run --function main

# Pass named function inputs
stoffel run --input a=40 --input b=2

# Load named inputs from json/csv/txt
stoffel run --input-file inputs.json

# Print function and instruction metadata before executing
stoffel run --program-info
```

For programs that use `ClientStore.take_share`, provide client-provided private inputs by numeric slot:

```bash theme={null}
stoffel run \
  --client-input 0=42 \
  --expected-output-clients 1 \
  --parties 5 \
  --threshold 1
```

Local MPC is the default unless `--network` or `--config` is set. A local run spawns several MPC nodes/processes on your machine using the configured `parties` and `threshold`.

## Development watch mode

`stoffel dev` runs a project through local MPC, then watches `Stoffel.toml` and source files for changes:

```bash theme={null}
stoffel dev \
  --parties 5 \
  --threshold 1
```

For scripts and CI, run once and exit:

```bash theme={null}
stoffel dev --once
```

Tune watch latency with `--poll-ms`:

```bash theme={null}
stoffel dev --poll-ms 250
```

## Testing

`stoffel test` runs no-argument test functions from a project or test file. By default it searches recursively under `tests/`.

```bash theme={null}
stoffel test
stoffel test tests/math.stfl
stoffel test --test addition
stoffel test --verbose
```

Use local MPC execution for tests that need several local MPC nodes instead of the embedded no-network test runner:

```bash theme={null}
stoffel test
```

## Status, clean, and update

```bash theme={null}
# Project health and environment diagnostics
stoffel status
stoffel doctor --verbose

# Remove generated target artifacts
stoffel clean
stoffel clean --dry-run
stoffel clean --all

# Check update actions without mutating files
stoffel update --check

# Reinstall the CLI from a source checkout
stoffel update --self-from-source
```

## Debugging tips

* Run `stoffel check --print-ir` before investigating runtime behavior.
* Run `stoffel run --program-info` to inspect function and instruction metadata.
* Use `stoffel compile --disassemble <file.stflb>` to inspect bytecode.
* Use the Rust SDK wrapper when you want application code to compile and run the same Stoffel program.

## Next steps

* [Quick Start](./quick-start)
* [CLI Overview](../cli/overview)
* [Rust SDK Examples](../rust-sdk/examples)