CLI

Use wio when you want a fast terminal loop: prepare a project, start a simulation, find failed runs, read logs, rerun cases, and verify the fix.

Install

npm install -g @workersio/cli

Then sign in:

wio auth login
wio auth status

Use wio auth logout to clear local credentials.

Output

Commands print readable tables by default. Add --format json when scripting.

wio workloads ls --state failed --format json

Projects

A project must be connected and prepared before it can run workloads. prepare fetches source, installs dependencies, runs .workers/build.sh when present, and builds the code image used by simulation VMs. Wait for the project to report synced before starting a simulation.

wio projects ls
wio projects ls --sync-status synced
wio projects get <project-id>
wio projects prepare <project-id>

Use the project ID from wio projects ls in simulation commands.

Start a Simulation

Run a baseline first. Baseline means no fault model is selected.

wio simulate create <project-id> \
  --workload-path .workers/workload.py \
  --command "python3 .workers/workload.py" \
  --depth 1

Then run with one or more fault models:

wio simulate create <project-id> \
  --workload-path .workers/workload.py \
  --command "python3 .workers/workload.py" \
  --faults slow-network,packet-loss \
  --depth 25 \
  --timeout 300 \
  --mem 1024

Fault names map to files under .workers/fault/net/. For example, --faults slow-network uses .workers/fault/net/slow-network.json.

Useful options:

• --workload-path: repo-relative workload file to capture with the run.
• --command: command executed for each run.
• --faults: comma-separated network fault names. Omit it for baseline.
• --depth: how much coverage to run for each selected fault model.
• --timeout: per-run timeout in seconds.
• --mem: memory limit in MB.
• --branch: branch to run instead of the project default.

Monitor Progress

wio simulate ls
wio simulate ls --state running
wio simulate status <simulation-id>
wio simulate cancel <simulation-id>

A simulation creates individual workload runs. Use workloads commands to find and inspect them.

wio workloads ls
wio workloads ls --simulation <simulation-id>
wio workloads ls --state failed

Run states are pending, booting, executing, succeeded, failed, timedOut, and interrupted.

Inspect a Run

wio workloads get <run-id>
wio workloads logs <run-id>

get shows the command, state, fault, branch, timing, failure category, and invariant results. logs prints the captured output.

Rerun and Verify

Rerun creates a fresh run with the same command, seed, fault model, memory, timeout, branch, workload file, and mock configuration. This is the same-seed determinism check. Replay is a separate record/playback tool for one recorded execution and is not the definition of determinism.

wio workloads rerun <run-id>

When a run fails, inspect the logs and captured files first. After you patch the bug, prepare the project and rerun that workload before increasing depth.

Workloads that need their own PRNG should derive it from WENV_SEED or FORMAL_SEED, not from wall time or a fresh root seed drawn during startup.

wio projects prepare <project-id>
wio simulate create <project-id> \
  --workload-path .workers/workload.py \
  --command "python3 .workers/workload.py" \
  --faults slow-network \
  --depth 25

Artifacts

Artifacts are files captured from a run, such as logs, command output, traces, or app-specific files.

wio artifacts ls <run-id>
wio artifacts download <run-id> stdout.log
wio artifacts download <run-id> stdout.log --output ./failed-run.log

Some large artifacts may be listed as metadata only and cannot be downloaded.

Environment and Host Status

wio env ls <project-id>
wio status

env ls shows the environment variable keys configured for a project. Values are not printed. status shows execution capacity and workload counts.