Getting started

1. Install the toolchain

Grab the latest release of the plugfy CLI from GitHub for your platform (Windows, Linux or macOS), put it on your PATH, and verify:

$ plugfy --version

One binary is all you need — the runner has no external dependencies. A Rust toolchain is only ever used (optionally) at build time to produce native accelerators; it is never a runtime dependency.

2. Your first program

A Plugfy source file (.plug) holds one namespace: types, functions, decisions and flows. Anything that touches the outside world — even printing — enters as a declared capability:

namespace hello

host fn print(s: string) -> int      // no body; the runtime implements it

fn main() -> int => print("Hello, Plugfy!")

Run it directly as a script, or build a portable image first:

$ plugfy run hello.plug              # direct script execution
Hello, Plugfy!

$ plugfy build hello.plug -o hello.fy   # portable image (~126 bytes!)
$ plugfy run hello.fy                   # runs on any OS with the runtime
Hello, Plugfy!

3. See what a program needs — before running it

Every function's effect row (the capabilities it can reach) is published in the compiled module. Inspect it without executing a single instruction:

$ plugfy inspect hello.fy
module hello
  1 function(s):
    [0] main() -> int  uses { print }
  requires 1 host capability(ies): print
  entry: function [0]

The runtime grants capabilities per least privilege: nothing touches the world that the program did not declare and the host did not permit. Read more in Capabilities & effect rows.

4. Your first flow

Flows express orchestration as data dependencies. Independent pure steps run in parallel automatically — with a result guaranteed identical to sequential execution:

flow profile(xs: List<int>) -> Stats {
    total = sum(xs)      // wave 0 — runs in parallel
    avg   = mean(xs)     // wave 0
    hi    = maxOf(xs)    // wave 0
    => Stats(total: total, avg: avg, hi: hi)
}

$ plugfy run stats.flow                    # run it
$ plugfy explain stats.flow                # show the inferred parallel waves
$ plugfy flow-graph stats.flow --dot       # export the dependency graph (Graphviz)

Continue in Flows & orchestration.

5. From files to projects

Loose files scale into projects. A project manifest (App.project.plugfy) declares governance: name, type, dependencies, targets and outputs. Building a project produces bin/App.fy plus its libraries:

$ plugfy build App.project.plugfy       # project -> bin/App.fy (+ bin/libraries/...)
$ plugfy native App.project.plugfy      # whole project -> standalone native binary

Where next?