> ## 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.

# Stoffel CLI Overview

> Use the Stoffel CLI to create, check, build, run, and iterate on private-computation projects.

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.

```bash theme={null}
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:

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
```

Check the available commands:

```bash theme={null}
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

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

Choose the template that matches your build path:

```bash theme={null}
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:

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

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

```toml theme={null}
[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](../mpc-protocols/overview) for backend selection guidance.

## Check source

Validate source and MPC settings without writing bytecode:

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

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

## Compile bytecode

Compile a project or source file to Stoffel bytecode:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
stoffel build
stoffel build --release
stoffel build -O2
```

## Run source or bytecode

Run the current project:

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

Run a specific file:

```bash theme={null}
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:

```bash theme={null}
cd /path/to/hello-mpc
stoffel dev \
  --parties 5 \
  --threshold 1 \
  --once

```

Run in watch mode by omitting `--once`:

```bash theme={null}
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:

```bash theme={null}
stoffel init --help
stoffel compile --help
stoffel run --help
stoffel dev --help
```