> ## Documentation Index
> Fetch the complete documentation index at: https://docs.transluce.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> The fxtr command-line interface.

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.

| Global option | Effect |
| - | - |
| `--project PATH` | A path inside the project to use. |
| `-q`, `--quiet` | Show only warnings from the runner. |
| `-v`, `--verbose` | Show the runner's debug output. |

## Projects

<ResponseField name="fxtr new DIRECTORY">
  Write a new project, ready to run: a uv project with an example experiment, a launcher, a
  renderer package, and guides for coding agents. It runs `git init` (unless the directory is
  already in a git or jj checkout) and `uv sync`. `--name` picks the project's name,
  `--no-views` omits the renderer package, and `--no-sync` skips `uv sync`.
</ResponseField>

<ResponseField name="fxtr init --database-url URL">
  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.
</ResponseField>

<ResponseField name="fxtr skills install">
  Install fxtr's guides for coding agents into the project, replacing older copies of fxtr's own
  guides and leaving other skills alone.
</ResponseField>

## Jobs

<ResponseField name="fxtr run WORKFLOW">
  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, and
  `--no-verify` skips checking the environment against `uv.lock`.
</ResponseField>

<ResponseField name="fxtr resume JOB">
  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` and `--no-verify` like
  `fxtr run`.
</ResponseField>

<ResponseField name="fxtr jobs list">
  List every job, newest first.
</ResponseField>

<ResponseField name="fxtr jobs status JOB">
  Show where a job is, and why it stopped.
</ResponseField>

<ResponseField name="fxtr jobs cancel JOB">
  Ask the process running a job to stop it.
</ResponseField>

## Cache

<ResponseField name="fxtr cache list">
  List the step cache's entries, oldest first, with each entry's state, address, and step.
</ResponseField>

<ResponseField name="fxtr cache clear [PREFIX]">
  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. `--key` names an exact address, `--step`
  limits clearing to one step's entries, `--state` to entries in one state, and `--all` clears
  everything.
</ResponseField>

## Viewer

<ResponseField name="fxtr view">
  Serve the experiment viewer for the project's jobs at `http://127.0.0.1:8000/`, and open it in
  a browser. `--no-open` only prints the URL, and `--host` and `--port` move it.
</ResponseField>

<ResponseField name="fxtr views build">
  Build the project's renderer package into its view bundle, which `fxtr view` serves. Reload the
  viewer afterwards.
</ResponseField>