WorldFlux Docs - BYO-compute physical-AI evaluation evidence

worldflux is a Typer application. Run any command with --help to see the same flag list inline.

Global flags

Global flags appear before the subcommand: worldflux --json runs list.

--json

boolean

Emit machine-readable JSON output where supported.

-v, --verbose

boolean (countable)

Increase diagnostic output. Repeat for more detail (-vv).

-q, --quiet

boolean

Suppress non-essential output.

--no-color

boolean

Disable colored terminal output.

--version

boolean

Print the WorldFlux version and exit.

Top-level commands

Command	Purpose
`worldflux init <project>`	Create a new project.
`worldflux run`	Run the project’s configured recipe/runtime and write artifacts.
`worldflux verify`	Verify manifest invariants.
`worldflux report`	Render `report.md` at the project root.
`worldflux visualize`	Render visual artifacts the recipe produced.
`worldflux compare`	Diff two project directories. Writes `comparison.md`.
`worldflux compare-runs`	Diff two run ids inside the same project.
`worldflux action-server`	Record local action traces.
`worldflux import`	Import an external model or dataset.
`worldflux export`	Export an adapter for an external eval harness.
`worldflux add`	Add an external recipe to the local catalog.
`worldflux doctor`	Run the local environment health check.
`worldflux identify`	Identify the world model attached to a project.
`worldflux ppi-augment`	Compute a PPI estimate from sim and real audit inputs.
`worldflux login / logout / status / sync`	Cloud session and upload.
`worldflux use <adapter>`	Install a curated adapter into `~/.worldflux/curated/<id>/`.
`worldflux uninstall <adapter>`	Remove an installed curated adapter.
`worldflux claim`	Create, inspect, draft, and falsify claim packages.
`worldflux evidence`	Inspect, diff, package, and cost-annotate evidence.
`worldflux audit`	Import, run, sign, verify, and publish audit packages.
`worldflux share`	Generate public-share approval templates for hosted evidence links.
`worldflux eval-profile`	Create and inspect local-private robotics/VLA eval profiles.
`worldflux eval-portfolio`	Plan and render local-private protocol plans, run sheets, eval packets, and reviewer briefs.
`worldflux vla-matrix`	Plan apple-to-apple VLA matrices and bind imported evidence.
`worldflux world-model-benchmark`	Inspect and score world-model benchmark protocols without launching benchmarks.
`worldflux lab`	Inspect lab prerequisites, EC2 orphans, and GPU sanity plans.
`worldflux schema / paper / museum / dd / positioning / billing`	Generate schema, paper, counterexample, diligence, standards, and billing artifacts.

`worldflux init`

worldflux init demo-box
worldflux init linear-box --recipe linear-world-model
worldflux init mlp-mujoco --recipe mlp-world-model --dataset mujoco-rollout

path

required

Project directory to create.

--recipe, -r

string

default:"cpu-smoke"

Built-in recipe id. List options with worldflux recipes list.

--dataset, -d

string

Dataset id for recipes that support dataset switching.

--force

boolean

Overwrite generated WorldFlux files.

`worldflux run`

worldflux run --project demo-box
worldflux run --project demo-box --runtime aws-ec2 --dry-run
worldflux run --project robot-box --control-trace traces/in.jsonl

The flag set is large because remote execution (AWS EC2, Modal) lives behind the same command.

--project, -p

path

default:"."

Project directory.

--runtime

string

Override the runtime declared in worldflux.yaml. Examples: local, modal, aws-ec2, replicate.

--dry-run

boolean

Plan remote execution without starting it. Prints the resolved instance type, region, and cost guard.

--input-video

path

Local MP4 to stage under inputs/ and send to remote video adapters.

--control-trace

path

Local JSONL trace recorded by worldflux action-server. Used by action-conditioned adapters.

AWS-only flags

various

--instance-type, --max-cost, --timeout, --region, --key-name, --key-path, --security-group-id, --subnet-id, --spot/--on-demand, --max-artifact-mb, --collect-large-artifacts/--skip-large-artifacts.

`worldflux import`

worldflux import lerobot:lerobot/pi0
worldflux import lerobot-dataset:lerobot/pusht

The CLI dispatches on the <scheme>:<id> prefix. Schemes today: lerobot:, lerobot-dataset:.

`worldflux export`

worldflux export --target vla-eval --model openpi --bench libero --output-dir exports

Today only --target vla-eval is wired.

`worldflux identify`

worldflux identify --project demo-box

Reads the project manifest and reports the connected recipe/adapter/runtime.

`worldflux ppi-augment`

worldflux ppi-augment --sim sim/audit_input.json --real real/audit_input.json --output ppi/

Computes ppi_estimate.json from paired simulation and real-world audit inputs.

`worldflux doctor`

Health check for Python, uv, runtime plugins, and (when logged in) the cloud session. The command also runs worldflux runtime doctor under the hood.

worldflux doctor
worldflux --json doctor

Cloud session

printf "Paste WorldFlux API key: "
IFS= read -r -s WORLDFLUX_TOKEN
echo
export WORLDFLUX_TOKEN

worldflux login \
  --api-url http://localhost:8000 \
  --token-env WORLDFLUX_TOKEN \
  --workspace <workspace-uuid> \
  --project <project-uuid>

unset WORLDFLUX_TOKEN

--token

string

Inline API key. Stored in shell history; prefer --token-env for CI.

--token-env

string

Read the API key from this env var, then drop it from memory.

--api-url

url

default:"http://localhost:8000"

Cloud control plane base URL.

--workspace

string

Default workspace UUID to remember for sync.

--project

string

Default project UUID to remember for sync.

--expires-at

ISO 8601

API key expiration time. Used for the warning prompt as the key approaches expiry.

--allow-plaintext

boolean

Fall back to ~/.worldflux/credentials.toml when the OS keyring is unavailable.

`worldflux logout`

Deletes the API key from the OS keyring (or credentials.toml) and clears the cached cloud config.

`worldflux status`

Prints workspace, project, plan, plan_status, run quota, storage quota.

`worldflux sync`

POSTs the current project’s manifest, metrics, logs, and committed artifact metadata. Idempotent on client_run_id. Artifact bytes go through signed URLs the cloud returns; the manifest itself is small.

Subcommand trees

`worldflux recipes`

worldflux recipes list
worldflux recipes inspect cpu-smoke

inspect prints the full recipe record, including known issues and the dataset id (if any).

`worldflux runs`

worldflux runs list --project demo-box
worldflux runs inspect <run_id> --project demo-box
worldflux runs export <run_id> --project demo-box --as-reproducer-pack runs/<run_id>.tar.gz

`worldflux datasets`

worldflux datasets list
worldflux datasets inspect mujoco-rollout

`worldflux curated`

The curated tree wraps the catalog adapters that ship with WorldFlux.

worldflux curated list
worldflux curated inspect cosmos_predict25
worldflux curated run cosmos_predict25 --task generate
worldflux curated deploy cosmos_predict25 --runtime modal
worldflux curated run-remote cosmos_predict25 --task generate
worldflux curated undeploy cosmos_predict25
worldflux curated status cosmos_predict25
worldflux curated runs list cosmos_predict25
worldflux curated runs inspect cosmos_predict25 <run_id>
worldflux curated runs latest cosmos_predict25

`worldflux installed`

Local installs of curated adapters.

worldflux installed list
worldflux installed inspect cosmos_predict25

`worldflux env`

Build and manage the per-adapter Python environments.

worldflux env build cosmos_predict25
worldflux env verify cosmos_predict25
worldflux env doctor cosmos_predict25
worldflux env shell cosmos_predict25
worldflux env exec cosmos_predict25 -- python -m pip list
worldflux env clean cosmos_predict25
worldflux env status

`worldflux runtime`

Inspect runtime plugins.

worldflux runtime list
worldflux runtime doctor

`worldflux cloud`

Use the dashboard to list/create workspaces and projects. The CLI stores the UUID selections used by sync and publish commands.

worldflux cloud workspace select <workspace-uuid>
worldflux cloud project select <project-uuid>

`worldflux claim`

worldflux claim create --template openpi-libero --output claim_pkg/
worldflux claim inspect claim_pkg/
worldflux claim from-paper-url https://arxiv.org/abs/... --output claim_pkg/
worldflux claim falsify clm_01HXY7K8ABCDEFGHJKMNPQRSTV

claim create writes both claim.json and protocol.json; from-paper-url creates a local draft without calling an external LLM.

`worldflux audit`

worldflux audit import lerobot --from /tmp/lerobot_run_001/eval_info.json --output audit_input.json
worldflux audit import cosmos-predict --from /tmp/cosmos/audit_input_cosmos_predict.json --output audit_input.json
worldflux audit import run-folder --from /tmp/customer_run --dry-run --report import_report.json --customer-report import_report_public.md
worldflux audit import run-folder --from /tmp/customer_run --select-run <candidate_id> --output audit_input.json --report import_report.json --customer-report import_report_public.md
worldflux audit run lerobot --from /tmp/lerobot_run_001/eval_info.json --claim claim_pkg/claim.json --protocol claim_pkg/protocol.json --output evidence_pkg/
worldflux audit sign evidence_pkg/
worldflux audit verify evidence_pkg/
worldflux audit publish evidence_pkg/ \
  --share \
  --cloud-run-id <cloud-run-uuid> \
  --confirm-public-share-upload \
  --approval-file public_share_approval.json \
  --password-env WORLDFLUX_SHARE_ACCESS_CODE
worldflux share approval-template \
  --approver-name "Example Reviewer" \
  --approver-role "Customer workspace owner" \
  --audience named_reviewer \
  --retention-policy delete_after_review \
  --customer-workspace-owner "Example Owner" \
  --output public_share_approval.json

Audit sources currently include lerobot, openpi, lbm_eval, vla-eval, gr00t-n1.7, pi-0.7, embodied-gov-bench, and cosmos-predict. cosmos-predict import expects a bridge-generated audit_input_cosmos_predict.json file or a directory containing that file. audit run can emit compliance mappings, ML-BOM sidecars, SAVI/PPI stopping metadata, and completeness scores for supported sources. run-folder is a read-only triage importer for already-extracted Physical AI run folders. It writes a private operator report and can also write --customer-report import_report_public.md, a public-safe Markdown summary with tier counts, claim-safe candidates, report-only signals, inventory-only artifact counts, rejection reasons, missing evidence labels, and next action. It only emits audit_input.json when a single selected candidate is claim-safe; audit run run-folder is intentionally unsupported in the MVP. audit publish --share requires Cloud login, a signed and verified evidence package, and either --cloud-run-id <cloud-run-uuid> so the package can be uploaded to that Cloud run with --confirm-public-share-upload, or --evidence-package-artifact-id <artifact-uuid> to reuse an already uploaded evidence package artifact. Hosted public shares also require --approval-file and a reviewer access code. Prefer --password-env WORLDFLUX_SHARE_ACCESS_CODE; --password is kept for backward compatibility but can expose values in process listings.

worldflux share approval-template \
  --approver-name "Example Reviewer" \
  --approver-role "Customer workspace owner" \
  --audience named_reviewer \
  --retention-policy delete_after_review \
  --customer-workspace-owner "Example Owner" \
  --output public_share_approval.json

share approval-template writes the customer approval file required by hosted public evidence shares. It does not upload artifacts, publish a share, or read the reviewer access code. The operator must review and sign the template before passing it to the hosted share publish command.

`worldflux evidence`

worldflux evidence inspect evidence_pkg/
worldflux evidence diff left/evidence.json right/evidence.json
worldflux evidence package --run-id <run_id> --output demo-box/outputs/runs
worldflux evidence capture-cost evidence_pkg/

Use this tree when the evidence already exists and you want to inspect, compare, repackage, or attach observed AWS cost.

`worldflux eval-profile` and `worldflux eval-portfolio`

eval-profile and eval-portfolio create local-private protocol plans and measured eval packets for robotics/VLA evidence review. The commands do not run benchmarks, upload artifacts, or decide deployment acceptability.

uv run worldflux eval-profile create --profile-id customer-vla-v3-tabletop --policy-id customer_vla_v3 --use-case "fixed-camera tabletop pick-and-place demo" --embodiment-class single_arm_tabletop --robot-model franka-panda --simulator-family libero --action-space end_effector_delta_pose --action-space gripper_action --action-control-mode delta_pose --coordinate-frame end_effector --degrees-of-freedom 6 --gripper-control binary --observation-space rgb_static_camera --observation-space language_instruction --camera-topology static --camera-config-id static-front-v1 --language-input --control-frequency-hz 20 --reset-policy episode_reset --metric-contract boolean_success_per_episode --real-to-sim-calibration calibration-v1 --environment-version libero-local --adapter-version worldflux-libero-bridge --training-exposure-possible-benchmark-family libero --training-exposure-caveat "operator did not provide a full training-data manifest" --claim-intent "constrained tabletop manipulation evidence" --reviewer-next-action "review conformance, missing cells, and unsupported claims" --output profile.json
uv run worldflux eval-portfolio plan --profile profile.json --seed 1234 --seed-source operator_supplied --custom-eval-contract contract.json --output plan.json
uv run worldflux eval-portfolio render-plan --plan plan.json --output plan.md
uv run worldflux eval-portfolio render-run-sheet --plan plan.json --output run_sheet.md --run-sheet-json run_sheet.json
uv run worldflux eval-portfolio packet --plan plan.json --audit-input libero-pro=audit_libero.json --audit-input libero-plus=audit_libero_plus.json --output packet.md --packet-json packet.json
uv run worldflux eval-portfolio reviewer-brief --packet packet.json --packet-markdown-ref packet.md --output reviewer_brief.md --brief-json reviewer_brief.json

Every generated artifact is LOCAL_PRIVATE and not public-share-ready. Reviewer briefs keep redaction and customer-consent limitations visible. WorldFlux records declared consent markers but does not verify legal consent validity. eval-profile create requires at least one training-exposure disclosure plus --training-exposure-caveat. eval-portfolio packet accepts repeatable --audit-input <probe_id>=<path> values and checks each episode against the frozen protocol plan before rendering a packet. Use --strict-missing-evidence when missing or underpowered evidence should fail packet generation instead of rendering as warnings.

`worldflux vla-matrix`

worldflux vla-matrix list
worldflux vla-matrix plan \
  --model openvla \
  --benchmark libero-standard-full \
  --episode-manifest episode_manifest.json \
  --frozen-by reviewer \
  --output matrix_plan.json \
  --run-sheet matrix_run_sheet.md
worldflux vla-matrix bind \
  --plan matrix_plan.json \
  --episode-manifest episode_manifest.json \
  --audit-input <matrix_cell_id>=audit_input.json \
  --output matrix_packet.json

The VLA matrix commands plan matrix cells and bind already imported episode evidence back to the frozen matrix. They do not launch GPU benchmark execution. Before collecting or publishing VLA benchmark data, choose the evidence grade and freeze the model, protocol, episode manifest, attempt policy, denominator policy, and scoring rule as described in the VLA preflight runbook.

`worldflux world-model-benchmark`

worldflux world-model-benchmark list
worldflux world-model-benchmark inspect <benchmark-id>
worldflux world-model-benchmark score --input benchmark_score_input.json --output benchmark_score.json

World-model benchmark commands inspect registered protocol definitions and score local benchmark inputs. They are not a hosted model runtime and do not upload private weights or datasets.

`worldflux lab`

worldflux lab doctor --runtime aws-ec2
worldflux lab cleanup-orphans
worldflux lab cleanup-orphans --apply
worldflux lab plan gpu-sanity --runtime aws-ec2 --instance-type g5.xlarge

Lab commands are read-only unless cleanup-orphans --apply is used.

Publishing and business artifacts

worldflux schema publish --output schemas/public
worldflux paper render --output paper/worldflux-evidence.md
worldflux museum add counterexample.json
worldflux museum list
worldflux museum export
worldflux dd render --evidence evidence_pkg/ --investor "Example Fund" --portfolio-company "WorldFlux" --decision-context "pilot renewal" --output outputs/dd
worldflux positioning render --output docs/positioning/standards-2026.md
worldflux billing invoice --pilot-id pilot_001 --amount-usd 5000 --dry-run --output invoice.json

These commands render artifacts around the evidence layer rather than running models.

Error envelope

When the CLI fails, it writes a JSON envelope to stdout and exits non-zero:

{
  "error": {
    "code": "init_failed",
    "message": "Init failed: directory already exists",
    "hint": "Use --force only when overwriting generated WorldFlux files is intended.",
    "doc_url": "https://docs.worldflux.ai/quickstart"
  }
}

The code is stable (e.g. init_failed, login_token_env_missing, credentials_unavailable). The message is human-facing and may change between versions.

​Global flags

​Top-level commands

​worldflux init

​worldflux run

​worldflux import

​worldflux export

​worldflux identify

​worldflux ppi-augment

​worldflux doctor

​Cloud session

​worldflux login

​worldflux logout

​worldflux status

​worldflux sync

​Subcommand trees

​worldflux recipes

​worldflux runs

​worldflux datasets

​worldflux curated

​worldflux installed

​worldflux env

​worldflux runtime

​worldflux cloud

​worldflux claim

​worldflux audit

​worldflux share

​worldflux evidence

​worldflux eval-profile and worldflux eval-portfolio

​worldflux vla-matrix

​worldflux world-model-benchmark

​worldflux lab

​Publishing and business artifacts

​Error envelope

Global flags

Top-level commands

`worldflux init`

`worldflux run`

`worldflux import`

`worldflux export`

`worldflux identify`

`worldflux ppi-augment`

`worldflux doctor`

Cloud session

`worldflux login`

`worldflux logout`

`worldflux status`

`worldflux sync`

Subcommand trees

`worldflux recipes`

`worldflux runs`

`worldflux datasets`

`worldflux curated`

`worldflux installed`

`worldflux env`

`worldflux runtime`

`worldflux cloud`

`worldflux claim`

`worldflux audit`

`worldflux share`

`worldflux evidence`

`worldflux eval-profile` and `worldflux eval-portfolio`

`worldflux vla-matrix`

`worldflux world-model-benchmark`

`worldflux lab`

Publishing and business artifacts

Error envelope