# one-run

CLI wrapper for reproducible ML experiment runs on local machines and SLURM

## install

```bash
pip install -e .
```

published package install:

```bash
pip install one-run1
```

## commands

- `one-run --version`: print installed package version
- `one-run run <manifest.yaml>`: execute locally (blocking)
- `one-run run --watch <manifest.yaml>`: execute locally in background
- `one-run submit <manifest.yaml>`: submit to SLURM
- `one-run status <run_id>`: inspect run status
- `one-run status -l <run_id>`: extended run status (metadata/runtime/paths)
- `one-run status <run_id> --json`: machine-readable status payload for scripts/CI
- `one-run cancel <run_id>`: cancel a running local watch or SLURM run.
- `one-run cancel --force <run_id>`: force-kill local run (SIGKILL) / SLURM KILL signal.
- `one-run ls`: list runs.
- `one-run ls --long`: detailed run list.
- `one-run ls --state success`: filter by state.
- `one-run validate <manifest.yaml>`: validate manifest + placeholders.
- `one-run tail <run_id> [-n 30] [--stderr] [-f] [--since 10m]`: tail run logs.
- `one-run gc [--state failed] [--older-than 7d] [--dry-run]`: cleanup run directories.

## run directory

```text
runs/<run_id>/
  config.snapshot.yaml
  metadata.json
  status.json
  runtime.json
  local.pid
  local.exit_code
  logs/stdout.log
  logs/stderr.log
  artifacts/
  metrics/
```
