# Magefile Reference

Epimetheus uses [Mage](https://magefile.org/) for build, test, and run targets. The build logic lives in `Magefile.go` at the repo root.

## Prerequisites

```bash
go install github.com/magefile/mage@latest
```

## Default Target

Running `mage` with no arguments runs **Build**.

## Targets

| Target | Description | Example |
|--------|-------------|---------|
| `build` | Compile the epimetheus binary | `mage build` |
| `install` | Install binary to `$GOPATH/bin` | `mage install` |
| `run` | Build and run in realtime mode (continuous) | `mage run` |
| `runHistoric` | Build and run historic mode (24h ago) | `mage runHistoric` |
| `runAuto <file>` | Build and run auto mode with a file | `mage runAuto test-all-ages.csv` |
| `runWatchClickHouse [file]` | Build and run watch mode with ClickHouse only | `mage runWatchClickHouse` or `mage runWatchClickHouse my.csv` |
| `test` | Run all tests | `mage test` |
| `testCoverage` | Run tests and open coverage report | `mage testCoverage` |
| `testRace` | Run tests with race detector | `mage testRace` |
| `benchmark` | Run Go benchmarks | `mage benchmark` |
| `lint` | Run golangci-lint | `mage lint` |
| `fmt` | Format all Go code | `mage fmt` |
| `vet` | Run go vet | `mage vet` |
| `tidy` | Run go mod tidy | `mage tidy` |
| `clean` | Remove binary and coverage artifacts | `mage clean` |
| `generate` | Run go generate | `mage generate` |
| `version` | Build and print version | `mage version` |
| `all` | Run fmt, vet, test, and build | `mage all` |
| `ci` | Tidy, vet, test, and build (CI pipeline) | `mage ci` |
| `dev` | Build, port-forward Pushgateway, run realtime mode | `mage dev` |
| `generateTestData` | Generate test data files | `mage generateTestData` |
| `backfill` | Run backfill for last 48 hours | `mage backfill` |
| `benchmark100MB` | Run 100MB benchmark script | `mage benchmark100MB` |
| `benchmark1GB` | Run 1GB benchmark script | `mage benchmark1GB` |
| `cleanupBenchmarkData` | Clean benchmark data from Prometheus | `mage cleanupBenchmarkData` |
| `cleanupBenchmarkMetrics` | Clean benchmark metric files | `mage cleanupBenchmarkMetrics` |
| `deployDashboard` | Deploy Grafana dashboard via script | `mage deployDashboard` |
| `help` | Print list of targets | `mage help` |

## Examples

```bash
# Build and run realtime mode
mage run

# Run tests with coverage
mage testCoverage

# Run watch mode with ClickHouse (default test file)
mage runWatchClickHouse

# Run watch mode with your CSV
mage runWatchClickHouse /path/to/data.csv

# Full CI checks
mage ci
```

See [Quick Start](../guides/quickstart.md) and [CLI Reference](cli.md) for more on running Epimetheus.