CLI reference

Run Falz from the project root. Use falz help, falz <command> --help, or falz <command> <subcommand> --help for built-in help.

Global options

These options apply to commands that load a project:

Option	Meaning
`--output PATH`	Override the configured output directory.
`--verbose`, `-v`	Increase logging. Repeat as `-vv` or `-vvv` for debug and trace.
`--silence`	Disable command output.
`--trust-pipes`	Suppress the warning for custom pipes with outbound HTTP permissions. It does not grant permissions.
`--version`, `-V`	Print version.
`--help`, `-h`	Show help.

Putting global options before the command is clearest:

falz -vv --output public build

`falz init`

Initialize .falz/, dist/, the starter layout, shared pipe directory, and TypeScript declarations.

falz init [--output DIR] [--activate LIST]

Option	Default	Meaning
`--output DIR`	`dist`	Create and configure this output directory. This is the init command's local option.
`--activate LIST`	`md`	Comma-separated built-in names accepted by the scaffold: `md`, `tpl`. Unknown names are skipped with a warning.

The command fails if .falz/ already exists. Its generated configuration contains the selected output directory and built-in pipes; all other values use normal defaults. See Configuration.

`falz add pipe`

Scaffold a custom TypeScript pipe.

falz add pipe NAME [--entrypoint FILE.ts] [--index]

Argument/option	Default	Meaning
`NAME`	required	Directory and initial pipe name.
`--entrypoint FILE.ts`	`index.ts`	Configured TypeScript entry point. The current scaffold still creates `index.ts`, so rename it yourself when choosing another filename.
`--index`	false	Include `index()`, `transform()`, and an empty KV contract.

The command also creates or refreshes .falz/pipes/tsconfig.json. It does not edit the project's pipes list and does not install npm packages.

`falz index`

Run index() for dirty entries and persist blobs/KV data.

falz index [--force]

--force re-indexes every entry with an index() export.

Run this before a one-shot build when indexed inputs changed. Full behavior is in Index phase.

`falz build`

Build dirty entries.

falz build [--debug] [--force] [--disable-cache]

Option	Meaning
`--debug`	Enable the project diagnostic flag for this run. For custom bundle output, set the pipe's own `debug: true`.
`--force`	Schedule every discovered entry, ignoring the manifest's build-dirty result. Forced entries run their transforms instead of being restored from the build cache.
`--disable-cache`	Disable build-CAS reads and writes for this command. Normal manifest dirty checking still skips unchanged entries.

Combine --force --disable-cache when you need every transform to run without reading or writing the artifact cache. Neither option clears existing state; the clean subcommands do that.

This command consumes existing index blobs and KV data but does not call index(). Run falz index first when indexed inputs changed. See Build phase.

`falz watch`

Perform an initial index/build, watch for changes, and rebuild incrementally.

falz watch [--disable-cache] [--serve] [--port PORT] [--hot-reload] [--open=false]

Option	Meaning
`--disable-cache`	Disable output CAS for this process.
`--serve`	Serve the output directory over HTTP.
`--port PORT`, `-p PORT`	Require this port. Without an explicit flag, watch tries the configured port and searches alternatives when it is busy.
`--hot-reload`	Notify connected pages after builds. Requires `--serve` or `watch.server.serve: true`.
`--open`, `--open=false`	Enable or disable opening a browser when serving.

To receive reload notifications, pages need the development client:

<script src="/falz-hotreload.js"></script>

Use that only in development output. The server also exposes /ws for the client connection.

`falz graph`

Scan the project and write its dependency graph to standard output:

falz graph > falz.graphml

The emitted GraphML contains nodes for entries, layouts, templates, fragments, pipes, and KV namespaces, with directed edges from dependents to their dependencies. Open the file with a GraphML-capable viewer such as yEd.

Use this command when a file did not match a layout or an expected dependency did not trigger a rebuild.

`falz config`

Print the effective project configuration as YAML:

falz config

The output includes comments, absolute source/output/scheme/pipe paths, resolved defaults, and computed cache paths. Fields marked read-only are informational and cannot be configured directly.

`falz clean`

Cleaning is explicit; there is no bare falz clean action.

Clear stores

falz clean cache
falz clean index
falz clean output
falz clean all

Command	Effect
`clean cache`	Delete build output CAS and clear its build-hash references.
`clean index`	Delete blob/KV caches and clear index references.
`clean output`	Delete everything in the output directory, including manifest and untracked files.
`clean all`	Run all three operations.

Remove orphan output

falz clean orphans output
falz clean orphans all

Both forms prune output files not referenced by the manifest and remove empty directories. They preserve referenced outputs and .manifest.json; index and build caches are not pruned in orphan mode.

For automatic cleanup after deleted sources or changed layout patterns, set build.clean: true. During each build, Falz removes outputs belonging to manifest entries that are absent from the newly scanned graph.

Cleaning output can remove files Falz did not create. Keep hand-owned files outside the output directory.