> ## Documentation Index > Fetch the complete documentation index at: https://docs.worldflux.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI reference > The Typer-based worldflux CLI. Top-level commands plus recipes, runs, datasets, curated adapters, runtime, cloud, claim, evidence, audit, lab, and publishing sub-trees. `worldflux` is a [Typer](https://typer.tiangolo.com/) 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`. Emit machine-readable JSON output where supported. Increase diagnostic output. Repeat for more detail (`-vv`). Suppress non-essential output. Disable colored terminal output. Print the WorldFlux version and exit. ## Top-level commands | Command | Purpose | | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `worldflux init ` | 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 ` | Install a curated adapter into `~/.worldflux/curated//`. | | `worldflux uninstall ` | 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` ```bash theme={null} worldflux init demo-box worldflux init linear-box --recipe linear-world-model worldflux init mlp-mujoco --recipe mlp-world-model --dataset mujoco-rollout ``` Project directory to create. Built-in recipe id. List options with `worldflux recipes list`. Dataset id for recipes that support dataset switching. Overwrite generated WorldFlux files. ### `worldflux run` ```bash theme={null} 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 directory. Override the runtime declared in `worldflux.yaml`. Examples: `local`, `modal`, `aws-ec2`, `replicate`. Plan remote execution without starting it. Prints the resolved instance type, region, and cost guard. Local MP4 to stage under `inputs/` and send to remote video adapters. Local JSONL trace recorded by `worldflux action-server`. Used by action-conditioned adapters. `--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` ```bash theme={null} worldflux import lerobot:lerobot/pi0 worldflux import lerobot-dataset:lerobot/pusht ``` The CLI dispatches on the `:` prefix. Schemes today: `lerobot:`, `lerobot-dataset:`. ### `worldflux export` ```bash theme={null} worldflux export --target vla-eval --model openpi --bench libero --output-dir exports ``` Today only `--target vla-eval` is wired. ### `worldflux identify` ```bash theme={null} worldflux identify --project demo-box ``` Reads the project manifest and reports the connected recipe/adapter/runtime. ### `worldflux ppi-augment` ```bash theme={null} 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. ```bash theme={null} worldflux doctor worldflux --json doctor ``` ## Cloud session ### `worldflux login` ```bash theme={null} 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 \ --project unset WORLDFLUX_TOKEN ``` Inline API key. Stored in shell history; prefer `--token-env` for CI. Read the API key from this env var, then drop it from memory. Cloud control plane base URL. Default workspace UUID to remember for `sync`. Default project UUID to remember for `sync`. API key expiration time. Used for the warning prompt as the key approaches expiry. 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` ```bash theme={null} 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` ```bash theme={null} worldflux runs list --project demo-box worldflux runs inspect --project demo-box worldflux runs export --project demo-box --as-reproducer-pack runs/.tar.gz ``` ### `worldflux datasets` ```bash theme={null} worldflux datasets list worldflux datasets inspect mujoco-rollout ``` ### `worldflux curated` The curated tree wraps the catalog adapters that ship with WorldFlux. ```bash theme={null} 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 worldflux curated runs latest cosmos_predict25 ``` ### `worldflux installed` Local installs of curated adapters. ```bash theme={null} worldflux installed list worldflux installed inspect cosmos_predict25 ``` ### `worldflux env` Build and manage the per-adapter Python environments. ```bash theme={null} 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. ```bash theme={null} 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. ```bash theme={null} worldflux cloud workspace select worldflux cloud project select ``` ### `worldflux claim` ```bash theme={null} 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` ```bash theme={null} 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 --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 \ --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 ` so the package can be uploaded to that Cloud run with `--confirm-public-share-upload`, or `--evidence-package-artifact-id ` 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` ```bash theme={null} 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` ```bash theme={null} worldflux evidence inspect evidence_pkg/ worldflux evidence diff left/evidence.json right/evidence.json worldflux evidence package --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. ```bash theme={null} 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 =` 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` ```bash theme={null} 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 =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` ```bash theme={null} worldflux world-model-benchmark list worldflux world-model-benchmark inspect 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` ```bash theme={null} 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 ```bash theme={null} 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: ```json theme={null} { "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.