CLI reference

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 CPU smoke job.
`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 login / logout / status / sync`	Cloud session and upload.
`worldflux use <adapter>`	Switch the project to an installed curated adapter.
`worldflux uninstall <adapter>`	Remove an installed curated adapter.

`worldflux init`

worldflux init demo-box
worldflux init linear-box --recipe linear-world-model
worldflux init shapenet-box --recipe vector-control-smoke --dataset shapenet

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 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 research-eval \
  --project demo-box

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 slug to remember for sync.

--project

string

Default project slug 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 --output-dir runs/export

`worldflux datasets`

worldflux datasets list
worldflux datasets inspect shapenet

`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 clean cosmos_predict25
worldflux env status

`worldflux runtime`

Inspect runtime plugins.

worldflux runtime list
worldflux runtime doctor

`worldflux cloud`

Workspace and project management mirrors what the dashboard exposes.

worldflux cloud workspace list
worldflux cloud workspace create --name "Research Eval"
worldflux cloud workspace select <slug>

worldflux cloud project list
worldflux cloud project create --workspace research-eval --name "Demo Box"
worldflux cloud project select <slug>

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.

Get started

Concepts

Reference

Global flags

Top-level commands

`worldflux init`

`worldflux run`

`worldflux import`

`worldflux export`

`worldflux doctor`

Cloud session

`worldflux logout`

`worldflux status`

`worldflux sync`

Subcommand trees

`worldflux recipes`

`worldflux runs`

`worldflux datasets`

`worldflux curated`

`worldflux installed`

`worldflux env`

`worldflux runtime`

`worldflux cloud`

Error envelope

Get started

Concepts

Reference

Documentation Index

​Global flags

​Top-level commands

​worldflux init

​worldflux run

​worldflux import

​worldflux export

​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

​Error envelope

Global flags

Top-level commands

`worldflux init`

`worldflux run`

`worldflux import`

`worldflux export`

`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`

Error envelope