# Usage (/docs/quickstart)
This page is the user-facing path for running WorldFoundry. It keeps the day-one workflow in one place; deeper pages are for details and edge cases.
Most runs follow the same shape even when the model or benchmark changes. First make the Python environment importable, then put checkpoints and benchmark assets in local cache directories, then generate artifacts, and only then score those artifacts.
## Workflow [#workflow]
Create the conda environment and source WorldFoundry paths.
Prepare only the model checkpoints, benchmark data, and metric assets needed for the run.
Use the TUI when you want an interactive command builder, or use the CLI commands below when scripting.
Run inference first. Run benchmark scoring only after generated artifacts match the benchmark layout.
## 1. Environment [#1-environment]
The bootstrap step creates the default WorldFoundry runtime and writes a local shell file with the paths used by the CLI, Studio, and evaluation runners. Always source that file before running commands in a new shell; it is the piece that tells WorldFoundry where your cache, datasets, checkpoints, conda envs, and outputs live.
Start from the repository root:
```bash
git clone https://github.com/OpenEnvision/WorldFoundry.git
cd WorldFoundry
bash scripts/setup/bootstrap_worldfoundry.sh
source tmp/worldfoundry_unified_env.sh
conda activate "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}"
```
On shared machines, keep datasets, checkpoints, and outputs outside git. This keeps the repository clean for open source release, avoids accidental commits of generated media, and lets multiple benchmark runs reuse the same local asset roots:
```bash
bash scripts/setup/bootstrap_worldfoundry.sh \
--home /path/to/worldfoundry-home \
--data-root /path/to/worldfoundry-data \
--model-root /path/to/worldfoundry-models \
--artifact-root /path/to/worldfoundry-artifacts
```
Verify an existing machine before a run. This is useful after logging into a fresh shell, moving to another GPU node, or changing CUDA/PyTorch packages:
```bash
bash scripts/setup/bootstrap_worldfoundry.sh --verify-only
worldfoundry-eval --help
```
Detailed environment mapping by model and benchmark lives in [Environment](/docs/reference/environments). Use that page when a model needs an extra conda profile or a benchmark evaluator depends on a metric package that is not part of the unified runtime.
## 2. Assets [#2-assets]
WorldFoundry keeps executable code in tree. Checkpoints, datasets, metric weights, reference files, and generated outputs are staged locally, usually through Hugging Face. The important distinction is that missing assets are expected to be downloaded or mounted.
Model assets and benchmark assets are separate. A model checkpoint lets you generate candidate artifacts; benchmark assets define what to generate, how outputs should be named, and which files or metric weights are needed to compute scores.
For a model:
```bash
bash scripts/inference/prepare_model_infer.sh --verify-env-only
bash scripts/inference/prepare_model_infer.sh --download
worldfoundry-eval zoo model-download --model-id --check-local --json
```
For a benchmark, start by asking WorldFoundry to print the asset plan. The plan shows the local paths, required environment variables, and the real evaluation command for that benchmark without downloading secrets or writing credentials:
```bash
python scripts/setup/prepare_benchmark_assets.py \
--benchmark-id \
--json
python scripts/setup/prepare_benchmark_assets.py \
--benchmark-id \
--write-env "${WORLDFOUNDRY_HOME:-${HOME}/.cache/worldfoundry}/.env" \
--create-dirs
source "${WORLDFOUNDRY_HOME:-${HOME}/.cache/worldfoundry}/.env"
```
Use `HF_TOKEN` only for gated assets whose terms you have accepted. Public checkpoints and datasets should work without a token; gated Hugging Face assets still require accepting the upstream license first:
```bash
export HF_TOKEN=
```
Full cache and path conventions are in [Local assets](/docs/guides/local-assets). If a command complains about a missing dataset, checkpoint, metric model, or generated output directory, that page explains where the file should live and which environment variable controls it.
## 3. TUI [#3-tui]
Use the TUI when you do not want to remember ids and flags. It is the best first-run path because it reads the same model and benchmark manifests as the CLI, shows the available choices, and can print the final command before anything expensive runs.
```bash
python -m pip install -e ".[tui]"
worldfoundry-eval tui
```
Generate a command without entering the interactive session. This is useful when you want the TUI to resolve ids and defaults, but you still want to paste the command into a job script or terminal multiplexer:
```bash
worldfoundry-eval tui \
--model-id \
--benchmark-id \
--print-command
```
The TUI does not bypass missing checkpoint, dataset, license, or environment requirements. If it prints a command for a benchmark whose assets are not staged yet, run the benchmark asset preparation step first and then retry the generated command.
## 4. CLI [#4-cli]
Use the CLI for scripts, batch jobs, and reproducible notes. Start with discovery commands instead of guessing ids: model ids, benchmark ids, and download declarations come from manifests, and the JSON output is easier to copy into automation.
Common discovery commands:
```bash
worldfoundry-eval zoo models --json
worldfoundry-eval zoo benchmarks --json
worldfoundry-eval zoo model-download --model-id --check-local --json
```
Run model inference from the command line. The output directory is intentionally explicit because later evaluation commands need to know where generated videos, frames, trajectories, or result files were written:
```bash
python -m worldfoundry.studio.workspace_job infer \
--model-id \
--prompt "a cinematic scene, high quality" \
--output-dir tmp/worldfoundry_infer/ \
--device cuda
```
For image-to-video or other conditioned models, pass an input file or directory along with the prompt and generation parameters. The exact supported flags depend on the selected model runner, so use this as the common shape and check the model page or TUI output for model-specific options:
```bash
python -m worldfoundry.studio.workspace_job infer \
--model-id \
--input-path /path/to/input.png \
--prompt "camera moves forward through the scene" \
--frames 81 \
--steps 30 \
--seed 42 \
--output-dir tmp/worldfoundry_infer/
```
The full command map is in [CLI](/docs/reference/cli). Use it as a reference after the main workflow is clear, not as the first page to read.
## 5. Inference [#5-inference]
Inference produces artifacts. It does not produce benchmark evidence by itself. A generated video can look correct in Studio and still fail a benchmark run if the filenames, prompt coverage, split, or metadata do not match what the benchmark runner expects.
The practical loop is: generate a small batch, inspect the outputs, confirm the directory layout, and then scale to the full prompt set required by the target benchmark. This avoids spending GPU time on outputs that cannot be scored later.
For repeated visual review, start the workspace:
```bash
bash scripts/workspace/run_workspace.sh
```
Open:
```text
http://127.0.0.1:7870/
```
Inspect the output directory or workspace gallery before scoring:
```bash
find tmp/worldfoundry_infer/ -maxdepth 2 -type f | head
```
More inference details are in [Run inference](/docs/guides/inference) and [Studio](/docs/guides/studio). Use Studio for visual review and the filesystem path for evaluation handoff.
## 6. Evaluation [#6-evaluation]
A benchmark run needs three concrete inputs. If any one is missing, the runner should stop with a blocked scorecard rather than silently producing a leaderboard-looking number.
| Input | Meaning |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Benchmark assets | Prompt/task metadata, reference files, official result files, judge credentials, simulator assets, or metric checkpoints. |
| Candidate artifacts | Videos, frames, rollouts, traces, or official-shaped result dumps produced by the model. |
| Runner mode | `official-validation` imports existing official-shaped results; `official-run` computes scores from generated artifacts. |
If the official benchmark already produced a result file, import it. This path is for normalizing and recording official-shaped results inside WorldFoundry without rerunning the upstream evaluator:
```bash
worldfoundry-eval zoo benchmark-run \
--benchmark-id \
--mode official-validation \
--official-results-path /path/to/official/results-or-report \
--generated-artifact-dir /path/to/generated/artifacts \
--output-dir tmp//official-validation \
--json
```
If generated artifacts are ready and the in-tree runner can compute metrics, run the integrated evaluator. This is the preferred path for benchmarks whose scoring code has been vendored and cleaned into WorldFoundry:
```bash
worldfoundry-eval zoo benchmark-run \
--benchmark-id \
--mode official-run \
--generated-artifact-dir /path/to/generated/artifacts \
--output-dir tmp//official-run \
--json
```
If a model-zoo model and benchmark-zoo runner support the one-cell path, WorldFoundry can launch the generation-and-scoring run from a single command. Use this only after assets and environment are known to be ready; otherwise it is harder to tell whether a failure came from generation or scoring:
```bash
worldfoundry-eval run \
--benchmark \
--model \
--mode official-run \
--output-dir tmp// \
--json
```
Open `scorecard.json` first. Public leaderboard claims require complete assets, complete generated artifacts, and the benchmark-specific eligibility flags. For debugging, also check the run manifest, per-sample results, and metric summaries written under the output directory.
## Where Details Live [#where-details-live]
This page is intentionally the common path. Once you know which model or benchmark you are running, jump to the specific page below for exact data layout, metric checkpoints, simulator notes, and model-specific arguments.