# CLI

Run and inspect simulations from the terminal.

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

```bash
npm install -g @workersio/cli
```

Then sign in:

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

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

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

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

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

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

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

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

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

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

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

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