> ## 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.

# Quickstart

> Three commands to a synced run. Five more to a comparison. The CLI keeps secrets in your keychain, never in the manifest.

## Install

<Steps>
  <Step title="Install uv">
    ```bash theme={null}
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```

    During beta, design partners install from a private checkout or private package index. Public PyPI installation will be documented after the public package release.
  </Step>

  <Step title="Sync the dev environment">
    ```bash theme={null}
    uv sync --extra dev
    ```

    From a checkout. For an installed package, skip to the next step.
  </Step>

  <Step title="Confirm the install">
    ```bash theme={null}
    uv run worldflux --version
    uv run worldflux doctor
    ```

    `doctor` checks Python, uv, every registered runtime plugin, and the cloud session if you are logged in.
  </Step>
</Steps>

## First local run

```bash theme={null}
uv run worldflux init demo-box
uv run worldflux run --project demo-box
uv run worldflux verify --project demo-box
uv run worldflux report --project demo-box
uv run worldflux visualize --project demo-box
```

`demo-box/outputs/` now holds a manifest, metrics, logs, run history, and any artifacts the recipe produced. `report.md` lands in `demo-box/`. Nothing left the machine.

<Tip>
  The default recipe is `cpu-smoke`. Pick a different one with `--recipe <id>`. List options with `worldflux recipes list` (recipes that ship: `cpu-smoke`, `vector-control-smoke`, `vision-smoke`, `linear-world-model`, `mlp-world-model`, `mujoco-smoke`, `mujoco-policy-eval`, `dreamer-style-light`, `libero-pro`, `libero-plus`).
</Tip>

## Sync to the cloud

<Warning>
  The CLI never echoes the API key to your shell history when you use `--token-env` or the interactive prompt. Avoid `--token <inline>` outside one-off debugging.
</Warning>

```bash theme={null}
printf "Paste WorldFlux API key: "
IFS= read -r -s WORLDFLUX_TOKEN
echo
export WORLDFLUX_TOKEN

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

unset WORLDFLUX_TOKEN
uv run worldflux sync --project demo-box --cloud-project-id <project-uuid>
```

The default `--api-url` is `http://localhost:8000`; point at a deployed cloud control plane in production. Create and list Cloud workspaces/projects in the dashboard, then use their UUIDs in the CLI. The dashboard now lists `demo-box`. Open it to inspect the synced run. Public share links are created from verified evidence-package artifacts, so package and verify evidence before sharing externally.

<Note>
  On machines with no OS keyring (some Linux containers), `worldflux login` fails until you pass `--allow-plaintext`. That writes the key to `~/.worldflux/credentials.toml`. In CI, prefer `--token-env` and short-lived secrets over plaintext storage.
</Note>

## Compare two runs

```bash theme={null}
uv run worldflux init linear-box --recipe linear-world-model
uv run worldflux run --project linear-box

uv run worldflux init mlp-box --recipe mlp-world-model
uv run worldflux run --project mlp-box

uv run worldflux compare linear-box mlp-box
```

`comparison.md` lands at the repo root with metric deltas, the chosen winner, and links to whichever artifacts (`prediction_plot.svg`, `rollout.html`, `rollout.mp4`) the recipes produced.

## Curated adapters

```bash theme={null}
uv run worldflux curated list
uv run worldflux curated inspect openpi
uv run worldflux use openpi
uv run worldflux env build openpi          # build the adapter's venv
uv run worldflux curated run openpi rollout
```

`worldflux use` clones the upstream adapter into `~/.worldflux/curated/<id>/`. The first call to `env build` resolves the adapter's `pyproject` and downloads dependencies or weights required by the upstream project. `curated run` reuses that environment.

## Package an audit

If you already have evaluation output, package it without rerunning the model:

```bash theme={null}
uv run worldflux claim create --template openpi-libero --output claim_pkg/
uv run worldflux audit import lerobot \
  --from /tmp/lerobot_run_001/eval_info.json \
  --output audit_input.json
uv run 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/
uv run worldflux evidence inspect evidence_pkg/
```

The package contains `claim.json`, `protocol.json`, `evidence.json`, provenance, and artifact metadata. Add `worldflux audit sign` and `worldflux audit verify` when reviewers need signed evidence. To create a public share that uploads sanitized evidence package bytes after Cloud login, verification, and explicit customer approval:

```bash theme={null}
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
```

To reuse an already uploaded package artifact, use:

```bash theme={null}
worldflux audit publish evidence_pkg/ \
  --share \
  --evidence-package-artifact-id <artifact-uuid> \
  --approval-file public_share_approval.json \
  --password-env WORLDFLUX_SHARE_ACCESS_CODE
```

## Where to go next

<CardGroup cols={2}>
  <Card title="CLI reference" icon="terminal" href="/cli/reference">
    Every top-level command and sub-tree, with `--json` examples for CI.
  </Card>

  <Card title="Dashboard" href="/dashboard">
    Sidebar, runs, compare, public share, billing.
  </Card>

  <Card title="Concepts" icon="book" href="/concepts/byo-model">
    BYO model, runtime plugins, eval bridges, anti-cherrypick eval packets.
  </Card>

  <Card title="FAQ" icon="circle-question" href="/faq">
    Edge cases, error messages, common slips.
  </Card>
</CardGroup>