CLI reference

This is a compact command reference. Use tfx <command> --help for exact argument syntax and defaults.

tfx check <file>

Compile through checking and GPU validation without running a window.

tfx check app.tfx
tfx check app.tfx --explain-passes
tfx check app.tfx --explain-passes=json

The explanation describes static source-to-pass lowering. It is useful for render draws, texture.step, parallel for, mip generation, candidates, and rejection/fallback reasons.

tfx run <file>

Run source or a .tfxb artifact in the native winit/wgpu host.

tfx run app.tfx
tfx run app.tfx --watch
tfx run app.tfx --trace-passes
tfx run app.tfx --profile
tfx run app.tfx --profile=json --duration 5s
tfx run app.tfx --duration 5s --screenshot frame.png
tfx run app.tfx --duration 3s --screenshot frame.png --viewport-size 1000x600 --screenshot-scale 0.5 --no-stats
tfx run app.tfx --screenshot frame@1s,2s
tfx run app.tfx --screenshot frame@1fps
tfx run app.tfx --storage-namespace com.example.paint
tfx run app.tfxb
tfx run app.tfxb --watch

With source input, --watch recompiles the entry file and its current import graph, then updates the watched import set. With .tfxb input, it watches only that artifact and reloads the replacement bytecode directly; it never tries to parse the artifact as source. A failed compile or artifact load leaves the previous program running so a later valid change can recover it.

--trace-passes reports native runtime pass selections once per observed selection. It is intentionally separate from compile-time explanations.

--storage-namespace NAME sets the host-owned identity used by storage::get/set/delete. Without it the CLI hashes the canonical entry path, so data persists for later runs of that entry. Set it explicitly when an application may move or when source and packaged .tfxb paths should share one namespace.

--profile reports raw wall-clock FPS, runtime CPU time, asynchronous GPU timings, pass counts, transfer/clear counters, and all named source profile scopes once per second and on exit. --profile=json emits the same profiling records as JSON Lines.

--duration Ns stops a native run after the requested number of seconds; fractional values such as 2.5s are accepted. --screenshot always writes PNG data and adds .png when the path has no extension. Without a schedule it captures the first completed frame, or the last frame when --duration is present. Append @2s, @1s,2s, or @1fps to override the schedule. Multiple captures use -001, -002, and so on before the extension. Every successful capture prints its path and elapsed run time to standard output.

--viewport-size WIDTHxHEIGHT sets the initial native viewport in physical pixels. --screenshot-scale SCALE rescales the written PNG after rendering, so a 1000x600 viewport with --screenshot-scale 0.5 produces a 500x300 screenshot even on a HiDPI display. While --viewport-size is present, the size requested by env.configureWindow(...) is ignored; the program's title, resizable, and fullscreen settings still apply. --no-stats suppresses every top-right stats line, including built-in FPS/timings and application-authored stat() values, even if the program calls env.showStats(true). The narrower --no-fps option continues to hide only built-in runtime lines.

tfx build <file>

Build a binary program or inspect target output:

tfx build app.tfx -o app.tfxb
tfx build app.tfx --emit-wgsl out/wgsl
tfx build app.tfx --emit-typescript out/app.ts
tfx build app.tfx --emit-webgpu out/webgpu
tfx build app.tfx --emit-webgpu out/webgpu --webgpu-wgsl sidecar
tfx build app.tfx --explain-passes=json

--emit-wgsl writes compiler-emitted shader/compute modules. --emit-webgpu writes physical pass artifacts and embeds WGSL unless sidecars are requested. --emit-typescript writes the structured generated-program target. See the artifact reference for the distinction.

tfx info <file>

Print stable program display metadata for source or .tfxb input:

tfx info app.tfx
tfx info app.tfxb

The information includes entry/per-file metadata and source identity. It is for display and tooling, not a durable application ID or a compatibility negotiation mechanism.

tfx fmt <paths...>

Format TinyFX source:

tfx fmt std examples
tfx fmt std examples --check

tfx reference

Generate the checked-in operation catalog from the Rust catalog:

tfx reference --format markdown -o docs/refs/operations.mdx
tfx reference --format json -o docs/refs/operations.json

The output is generated. Do not hand-edit either artifact.