The Faby CLI

#Overview

The Faby CLI follows the same philosophy as the language: zero configuration, one canonical way, machine-friendly output. Every command:

• works with no config file — conventions over configuration, always
• supports --json for structured output that agents and CI pipelines can parse
• returns deterministic, documented exit codes (see Exit Codes)
• is offline by default — AI-powered commands are explicit, opt-in and clearly marked

#Installation — NPM

The recommended way to install the Faby CLI is through NPM — the @fabycode/cli package is live. The v0.1 Genesis release ships the JavaScript runtime (the same engine as the browser playground); the platform-native binary replaces it transparently with v0.2.

# install globally (recommended)
$ npm i -g @fabycode/cli

# or run ad-hoc without installing
$ npx @fabycode/cli run hello.fy

# or add to a project as a dev tool
$ npm i -D @fabycode/cli

# verify the installation
$ faby version
faby 0.1.0 (genesis) — designed by claude-fable-5

Alternative install channels

# pin a specific version
$ npm i -g @fabycode/cli@0.1.0

# shell installer without Node — ships with v0.2 "Pulse"
$ curl -fsSL https://faby.codes/install.sh | sh   # coming soon

#Quick Start

$ npm i -g @fabycode/cli
$ faby init hello && cd hello
created hello/main.fy
created hello/faby.lock
$ faby run main.fy
Hello, Faby.
$ faby check
✓ 1 file · 0 errors · 2 contracts verified statically
$ faby build --native
→ hello (1.9 MB, static, 412ms)

#Anatomy & Global Flags

Global flags work on every command:

#faby init

Scaffold a new project. Creates the minimal canonical layout — a main.fy and a faby.lock. No config file, because there is nothing to configure.

$ faby init my-agent --agent
created my-agent/main.fy        (intent-annotated agent starter)
created my-agent/faby.lock
→ next: cd my-agent && faby run main.fy

#faby run

Execute a program with the tree-walking interpreter. Cold start under 50ms — built for tight agent loops and rapid iteration. Contracts are always enforced in run mode.

# run a crawler that may use the network but NOT the filesystem
$ faby run crawler.fy --cap net -- https://faby.codes
fetched 12 pages · 0 failures · 1.4s

# watch mode while developing
$ faby run server.fy --watch
▲ watching 3 files — last run OK (38ms)

#faby build

Ahead-of-time compilation through the Faby IR. Produces a single static binary or a WASM module. Builds are deterministic: same input, same byte-identical output, on any machine.

# release binary for a Linux server, built on a Mac
$ faby build server.fy --release --target linux-x64 -o dist/server
⠿ parse 12ms · check 31ms · prove 44ms · codegen 380ms
→ dist/server (2.3 MB, static, linux-x64)
  contracts: 17 proven statically, 3 runtime guards kept

# WASM for the browser, with TypeScript bindings
$ faby build engine.fy --wasm -o web/engine
→ web/engine.wasm (412 KB) · web/engine.d.ts · web/engine.js

#faby check

The full static pipeline without execution: parse, type-check, refinement inference, contract proving, lints. This is the command CI should run on every commit.

$ faby check --strict --json | jq '.summary'
{
  "files": 14,
  "errors": 0,
  "contracts": { "proven": 41, "guarded": 6 },
  "intents":   { "checked": 9, "drifted": 0 }
}

#faby fmt

Formats code into the one canonical form. On already-valid code, faby fmt changes nothing — it is the identity function. There are no options to configure, which is the point.

#faby test

Runs inline test blocks and auto-generates property-based tests from your contracts: every expect/ensure pair becomes a fuzzed property the runner attacks with generated inputs.

$ faby test --props 1000
✓ 23 tests · 8 contract properties × 1000 inputs · 0 failures (2.1s)
  slowest: transfer.conservation (312ms)

#faby repl

An interactive session with the full standard library. Multi-line flows, type inspection with :t, and instant reload of your project's flows with :load.

faby> [1, 2, 3] |> map(_ * 10) |> sum
60 : Int
faby> :t "ada@faby.codes"
Text — hint: Email.parse(…) to lift into a semantic type
faby> :load main.fy
loaded 4 flows from main.fy

#faby explain AI

Plain-language explanation of any Faby program: what it does, which contracts protect it, where the risks are. Works on files you wrote — or on generated code you're about to trust.

#faby gen AI

Generate a flow from an intent. The output always arrives with the intent block attached, contracts proposed, and faby check already passed — generation and verification in one step.

$ faby gen "dedupe a list of emails case-insensitively, keep first occurrence" \
    --sig "flow dedupe(xs: [Email]) -> [Email]" -o dedupe.fy
→ dedupe.fy · intent attached · 2 contracts proposed
✓ faby check passed before writing to disk

#faby review AI

Review a diff the way Faby thinks about code: does the change still satisfy each governing intent, are contracts weakened, did failure policies change. Designed to gate AI-generated pull requests.

#faby add / remove

Dependency management is lockfile-first and content-addressed: faby.lock pins exact content hashes, so a build can never silently change because a registry did.

$ faby add markdown@1.2
+ markdown 1.2.0 (sha256:9f2c…) → faby.lock
audited: no caps requested beyond fs:read

#faby publish

Publish a library to the Faby package index. Publishing runs the full gauntlet locally first: check --strict, test, fmt --check and a capability manifest review.

#faby doctor

Diagnoses the installation: binary integrity, PATH issues, Node bridge version, cache health, registry reachability. The first thing to run when something feels off.

$ faby doctor
✓ binary        faby 0.1.0 (genesis), darwin-arm64, signature OK
✓ node bridge   18.19.0 via @fabycode/cli
✓ cache         142 MB, healthy
✓ registry      reachable (89ms)
no issues found

#Shell Completions

# zsh
$ faby completions zsh > ~/.zfunc/_faby

# bash
$ faby completions bash >> ~/.bashrc

# fish
$ faby completions fish > ~/.config/fish/completions/faby.fish

#Environment Variables

#Exit Codes

Exit codes are part of the CLI's contract — stable across versions, safe to script against:

#CI Integration

The canonical CI pipeline is three commands. With NPM as the install channel it drops into any existing Node-based CI without new tooling:

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm i -g @fabycode/cli
      - run: faby fmt --check
      - run: faby check --strict --json
      - run: faby test --props 512

#Troubleshooting

faby: command not found after npm install

Your global npm bin directory is not on PATH. Run npm prefix -g and add its bin folder to PATH — or use npx @fabycode/cli as a zero-setup fallback.

AI commands fail with capability denied: ai

By design. Set FABY_API_KEY and grant the capability explicitly: faby run agent.fy --cap ai,net.

Build output differs between machines

It shouldn't — builds are deterministic. If you see a difference, run faby doctor and file a bug with both outputs; this is a release-blocking defect for us.

Anything else

Run faby doctor --json and open an issue, or ping @fabylanguage.