Skip to main content
Run fxtr from inside a project with uv run fxtr .... Every command works on the project containing the working directory; --project PATH names another. uv run fxtr COMMAND --help describes each command’s options.

Projects

Write an empty uv project that depends on this fxtr or a later one, with a Python package and an empty renderer bundle. Add --example to include a runnable greeting experiment, its launcher, greeting renderers, and a results overview. It runs git init (unless the directory is already in a git or jj checkout) and prints the setup commands, starting with uv sync. --name picks the project’s name.
Write fxtr.local.toml, which says where this machine reaches the project’s database, and create the project’s tables. The URL is a SQLAlchemy postgresql+asyncpg://... URL. --schema picks the database schema (by default fxtr_ followed by the project’s name), and --force replaces an existing file. The FXTR_DATABASE_URL environment variable overrides the file’s URL.

Jobs

Run a workflow, by its registered name, as a job in this process until it stops. --input NAME=VALUE passes an input as a JSON scalar, or as @ARRAY for a snapshot of a project array. --root sets the root pathname. --allow-staged includes staged changes in the pinned code, --no-verify skips checking the environment against uv.lock, and --overwrite-cache-conflicts reruns steps in cache conflict and replaces the old results. When the project’s viewer is running, its open tabs switch to the job, or it opens in a new tab when none is open; --no-open only prints the link.
Run a stopped job’s unfinished work in this process until it stops. It reuses the results the job already has and retries failed steps. Takes --allow-staged, --no-verify, --overwrite-cache-conflicts, and --no-open like fxtr run.
List every job, newest first.
Show where a job is, and why it stopped. A job’s cache conflicts are shown grouped into patterns, with the commands that resolve them.
Ask the process running a job to stop it.
Write a stopped or succeeded job’s record to a file: its facts, and every entity they reach, as a gzipped CAR file that another project can import.
Add the job in a record file written by fxtr jobs export to this project, with everything it reaches. The commits its results were produced at must exist in this repository, and the job must not be in the project already unless --update is given, which brings a job the project has up to date from a later record of it. The step cache is left alone unless --adopt-cache is given, which makes the cache offer the job’s results as fxtr cache adopt does; with it, --overwrite-cache-conflicts replaces entries that hold a different request’s result.

Cache

List the step cache’s entries, oldest first, with each entry’s state, address, and step. PATTERN limits the list to the entries at or under an address, where a mapped key’s value can be * ('root/count_words[prompt:*]'). --conflicts-in JOB lists the entries a job is in cache conflict with, --step one step’s entries, and --state entries in one state.
Forget the entries at or under an address, so the next job to request them runs the steps afresh. Jobs that already used a result keep it. PATTERN is as for fxtr cache list. --address names an exact address, --conflicts-in JOB the completed entries a job is in cache conflict with, and --all everything; --step and --state narrow any of these.
Make the cache offer the results a job used, local or imported, so later jobs reuse them. An address that holds a different request’s result is left alone unless --overwrite-cache-conflicts is given. PATTERN limits adoption as for fxtr cache list.

Viewer

Serve the experiment viewer for the project’s jobs and open it in a browser. It prefers the project’s last successful port, then tries 8000 through 8050. --no-open only prints the URL, --host sets the bind address, and --port requires an exact port and fails if it is taken. It builds the project’s view bundle if the renderers changed since the last build, then rebuilds it whenever they change while it runs, and open pages switch to the new renderers without a reload. Failed builds keep the last valid bundle, or the default renderers when none exists; the viewer shows the error and keeps watching for fixes. When the project’s viewer is already running, it opens that one and exits.
Copy the fxtr TypeScript packages the project’s renderers build against into views/vendor/fxtr/, replacing any earlier copy. Run it after upgrading fxtr, then pnpm install in views/. Commit the copy with the project.
Build the project’s renderer package into its view bundle, which fxtr view serves. A failed build keeps the previous bundle. A running fxtr view rebuilds the bundle by itself; this is for building without one.