AleoFlow

A single-binary developer CLI that wraps the Aleo toolchain (leo, and eventually snarkOS) into one consistent workflow: scaffold, build, test, audit, deploy, and generate TypeScript bindings for Aleo programs.

Built for the Aleo Hackathon 2026 — Infrastructure & Developer Tools track.

AleoFlow does not reimplement Leo's compiler or the Aleo network client. It wraps the official leo CLI and adds the parts that are missing from day-to-day developer workflow: project scaffolding with real templates, a lightweight privacy linter, and TypeScript client stub generation from a compiled program's ABI.

Why

Aleo's official tooling (leo, snarkOS) is powerful but fragmented — getting a new privacy-preserving program from idea to deployed contract means juggling several separate tools and remembering their exact flags. AleoFlow collapses that into one binary with one consistent interface, similar in spirit to tools like create-react-app or cargo itself: opinionated defaults, real templates, and no reinvention of the underlying compiler or network logic.

Prerequisites

• Rust (stable toolchain) — https://rustup.rs
• Leo — the Aleo compiler AleoFlow wraps:

  cargo install cargo-binstall
  cargo binstall leo-lang
  

  Verify with leo --version.
• snarkOS — only required for the devnet command (local test network). Install via leo devnet --install the first time you run aleoflow devnet.

Install

From source:

git clone <your-repo-url>
cd aleoflow
cargo install --path .

Or build a release binary and run it directly:

cargo build --release
./target/release/aleoflow --help

The binary is fully portable — project templates are embedded into it at compile time, so it works from any directory without needing the templates/ folder alongside it.

Quick Start

aleoflow init my-app --template payment
cd my-app
aleoflow build
aleoflow test
aleoflow audit .

Workflow

flowchart LR
    A[aleoflow init] --> B[aleoflow build]
    B --> C[aleoflow test]
    C --> D[aleoflow audit]
    D --> E{Looks good?}
    E -- No --> B
    E -- Yes --> F[aleoflow deploy]
    F --> G[aleoflow bindings]
    G --> H[Frontend / SDK integration]

    style A fill:#1f6feb,color:#fff
    style B fill:#1f6feb,color:#fff
    style C fill:#1f6feb,color:#fff
    style D fill:#8957e5,color:#fff
    style F fill:#da3633,color:#fff
    style G fill:#238636,color:#fff

Each stage wraps a real underlying tool rather than reinventing it — build/test/deploy/devnet shell out to the official leo binary, audit and bindings are AleoFlow-native additions that fill gaps the official toolchain doesn't cover.

Deploy safety flow

flowchart TD
    A["aleoflow deploy --network X"] --> B{--broadcast passed?}
    B -- No --> C[Dry run: compile + prepare only]
    C --> D[No transaction sent]
    B -- Yes --> E{network == mainnet?}
    E -- Yes --> F[Print mainnet warning]
    F --> G[Invoke leo deploy --broadcast]
    E -- No --> G
    G --> H{PRIVATE_KEY set?}
    H -- No --> I[leo errors out, no funds spent]
    H -- Yes --> J[Transaction broadcast to network]

    style D fill:#238636,color:#fff
    style I fill:#9a6700,color:#fff
    style J fill:#da3633,color:#fff

This mirrors leo deploy's own default behavior (dry-run unless --broadcast is explicit) rather than layering a separate confirmation system on top of it.

Commands

aleoflow init <name> --template <template>

Scaffolds a new Aleo project from a built-in template. Templates:

• payment — basic private transfer
• defi — deposit / withdraw pair
• ai-agent — simple agent state record + inference stub
• gamefi — player state / score submission record

Project names containing hyphens are automatically sanitized to underscores for the generated Aleo program ID (Aleo program identifiers cannot contain hyphens), while the folder name stays exactly as typed.

aleoflow init my-voting-app --template defi

aleoflow build [--path <path>] [--json-output[=<file>]]

Wraps leo build. Compiles the Leo program at path (or the current directory if omitted) into Aleo instructions.

aleoflow build --path my-app

aleoflow test [--path <path>] [--json-output[=<file>]]

Wraps leo test.

aleoflow test --path my-app

aleoflow audit <path>

A heuristic static linter for Leo source files — not a formal verifier. Flags:

• Sensitive-looking field names (password, secret, private_key, ssn, etc.) that may be unintentionally exposed
• Functions that return addresses or numeric values with no visible assert/require guard nearby (informational, best-effort)
• Leftover TODO/FIXME comments (informational)

aleoflow audit ./my-app

aleoflow deploy --path <path> --network <testnet|mainnet|canary> [--broadcast] [--endpoint <url>] [--json-output[=<file>]]

Wraps leo deploy. Runs in dry-run mode by default — it compiles and prepares the deployment but does not broadcast anything unless --broadcast is explicitly passed. This mirrors leo's own safety default rather than re-implementing a separate confirmation flow.

Deploying to mainnet with --broadcast prints an explicit warning before proceeding.

--endpoint overrides the target RPC endpoint (useful for pointing at a local leo devnet node instead of the public testnet API, e.g. during an outage on the public endpoint).

# Dry run — safe, does not deploy anything
aleoflow deploy --path my-app --network testnet

# Actually deploy to testnet
aleoflow deploy --path my-app --network testnet --broadcast

# Deploy against a local devnet instead of the public API
aleoflow deploy --path my-app --network testnet --broadcast --endpoint http://localhost:3030

Deployment requires a funded account. See Deploying for real below.

aleoflow devnet [--path <path>] [--network <network>]

Wraps leo devnet to start a local Aleo development network. Requires snarkOS; if it isn't installed, AleoFlow will tell you to run leo devnet --install.

aleoflow devnet --path my-app

aleoflow bindings <path> [--output <file>]

Generates TypeScript client stubs from a compiled program's ABI (build/<program_id>/abi.json, produced by leo build). If the ABI file doesn't exist yet, AleoFlow runs leo build automatically before generating bindings, so this command works even on a fresh project. Parameter names are pulled from the .leo source directly, since Leo's ABI JSON does not currently preserve them. Output defaults to <path>/bindings/<program_name>.ts.

Generated stubs are typed and named correctly but are not wired to the Aleo network — they're a starting point to reduce boilerplate, not a finished SDK integration. See https://docs.aleo.org/build/sdk/getting_started for wiring execution calls with @provablehq/sdk.

aleoflow bindings my-app

Proof of deployment

AleoFlow has been used to deploy a real program to Aleo testnet:

• Program: diag_test.aleo
• Transaction ID: at13ujqtwaj7vmyvjm6hewuk4wevp3x94lqrd3mywrr6jm4ml59yups7j4lts
• Explorer: https://explorer.aleo.org/transaction/at13ujqtwaj7vmyvjm6hewuk4wevp3x94lqrd3mywrr6jm4ml59yups7j4lts

Deployed with:

aleoflow deploy --path diag-test --network testnet --broadcast

Deploying for real

leo deploy (and therefore aleoflow deploy --broadcast) requires a funded private key. To set one up:

leo account new

Save the printed private key, view key, and address somewhere safe. Then get testnet credits from the official faucet:

https://faucet.aleo.org/

Set the key as an environment variable, or in a .env file in your project root:

ENDPOINT=https://api.explorer.provable.com/v1
NETWORK=testnet
PRIVATE_KEY=<your private key>

Then:

aleoflow deploy --path my-app --network testnet --broadcast

Note: the public testnet API (api.explorer.provable.com) can occasionally return connection timeouts (Cloudflare 522) or fail to resolve the latest block height under load. This is an infrastructure issue on Aleo's side, not a local configuration problem — if you hit it, wait a few minutes and retry. As a fallback that removes the dependency on the public API entirely, you can run a local devnet (leo devnet --snarkos ./snarkos-bin --install, then leo devnet --path my-app --snarkos ./snarkos-bin) and deploy against it with aleoflow deploy ... --endpoint http://localhost:3030.

--json-output and CI use

build, test, deploy, and devnet all support --json-output, forwarded directly to leo. This is intended for scripting and CI pipelines rather than interactive use — passing it suppresses the normal colored progress output in favor of a structured JSON result file.

aleoflow build --path my-app --json-output

Optional config: aleo.toml

AleoFlow will look for an aleo.toml file in the current directory and use it to fill in flags you didn't pass explicitly. CLI flags always take priority over the config file.

default_network = "testnet"

default_template = "payment"

• default_template — used by init when --template is omitted
• default_network — used by deploy and devnet when --network is omitted

If the file is missing, malformed, or simply not present, AleoFlow falls back to its built-in defaults and continues normally — a broken or absent aleo.toml never blocks the CLI.

Quiet mode

Every command accepts a global -q / --quiet flag that suppresses [info] status messages, useful when combined with --json-output for scripting or CI:

aleoflow build --path my-app --quiet --json-output

[warning], [done], [error], and audit findings are never suppressed — only informational status lines are silenced.

What AleoFlow does not do

• It does not re-implement Leo's compiler, the ZK proving system, or snarkOS's networking logic — all of that is handled by the official leo and snarkOS binaries, which AleoFlow wraps.
• audit is a heuristic linter for hackathon-demo purposes, not a security audit or formal verification tool.
• bindings generates typed stubs, not a complete SDK integration.

No license file included. All rights reserved unless otherwise stated.