git:20260525.2852069 to git:20260529.a192df3

---

name: fuelclock-nz

description: Query NZ fuel prices, supply, inbound tankers, MSO status, geopolitical shipping risk markets, and NZ fuel headlines from fuelclock.nz. No authentication required.

---

# FuelClock NZ

## Goal

Query live New Zealand fuel price and supply data from fuelclock.nz through a CLI that is easy for agents to script and easy for humans to scan. Includes geopolitical shipping risk markets and recent NZ fuel headlines.

## Use this when

- A user asks about current NZ petrol, diesel, or premium fuel prices

- A user wants to know whether NZ fuel supply is tight or below MSO thresholds

- A user asks what tankers are en route to New Zealand

- A user wants a quick fuel situation summary focused on prices, supply, and vessels

- A user asks about geopolitical shipping risk markets relevant to NZ fuel supply

- A user wants recent NZ fuel headlines

## Do not use this for

- Fuel prices outside New Zealand

- Electricity, gas, or LPG pricing

- Vehicle fuel efficiency calculations

- Forecasting future fuel prices beyond the live observed data

## Preferred workflow

2. Use `summary` for a quick situational briefing across prices, supply, and vessels

3. Use `watch` for a quick briefing across geopolitical risk markets and recent headlines

4. Use default human output for direct answers

5. Use `--json` when another tool or agent needs machine-readable output

## CLI

Run with:

```bash

```

### `summary [--json]`

Best default for general fuel questions. Combines prices, supply, and inbound vessels.

JSON shape:

- `prices`: fetched price snapshot plus filtered price rows

- `supply`: overall risk, countdown, lowest fuel, below-MSO list, and fuel rows

- `vessels`: fetched time, inbound vessel count, flagged count, and top vessels

Examples:

```bash

```

### `watch [--json]`

Quick briefing combining top geopolitical risk markets and recent NZ fuel headlines.

JSON shape:

- `risk.fetchedAt`, `risk.totalMarkets`, `risk.markets[]`

- `news.fetchedAt`, `news.totalArticles`, `news.articles[]`

Examples:

```bash

```

### `prices [--fuel 91|95|98|diesel] [--json]`

Shows national average NZ pump prices from FuelClock's Gaspy-backed endpoint.

JSON shape:

- `fetchedAt`

- `source`

- `isFallback`

- `filters.fuel`

- `count`

- `prices[]` with `fuel`, `label`, `price`, `change7d`, `change28d`, `changePercent28d`, `direction7d`, `direction28d`, `min`, `max`, `stationCount`

Examples:

```bash

```

### `supply [--fuel petrol|diesel|jet] [--below-mso] [--json]`

Shows NZ fuel supply state, including days remaining, MSO gap, and depletion timing.

JSON shape:

- `timestamp`

- `anchorDate`

- `mbieAsAtDate`

- `overallRisk`

- `countdownHours`

- `lowestFuel`

- `filters.fuel`

- `filters.belowMSO`

- `count`

- `fuels[]` with `fuel`, `label`, `currentDays`, `totalDays`, `onLandDays`, `onWaterDays`, `msoThreshold`, `gapToMSODays`, `belowMSO`, `calendarDaysToDepletion`, `dailyConsumptionML`, `currentStockML`, `remainingOnWaterDays`, `remainingOnWaterML`, `mbieInCountryDays`

Examples:

```bash

```

### `vessels [--fuel petrol|diesel|jet] [--flagged-only] [--limit N] [--json]`

Shows inbound vessel data, sorted by ETA.

JSON shape:

- `fetchedAt`

- `source`

- `govOnWaterByFuel`

- `filters.fuel`

- `filters.flaggedOnly`

- `filters.limit`

- `totalMatching`

- `returnedCount`

- `vessels[]` with `name`, `fuel`, `status`, `eta`, `arrived`, `cargoML`, `cargoDays`, `origin`, `progressPct`, `flagRisk`, `flagReason`, `hormuzTransit`

Examples:

```bash

```

### `risk [--limit N] [--json]`

Shows tracked geopolitical markets relevant to fuel shipping (Polymarket-style), sorted by trading volume.

JSON shape:

- `fetchedAt`

- `sort`

- `filters.limit`

- `totalMarkets`

- `returnedCount`

- `markets[]` with `title`, `shortTitle`, `probability`, `volume`, `liquidity`, `lastUpdated`, `isFallback`, `subMarkets[]`

Examples:

```bash

```

### `news [--limit N] [--json]`

Shows recent NZ fuel headlines, newest first.

JSON shape:

- `fetchedAt`

- `filters.limit`

- `totalArticles`

- `returnedCount`

- `articles[]` with `title`, `source`, `date`, `url`

Examples:

```bash

```

## Resources

## Notes

- No API key required

- Default output is human-readable and filtered for quick answers

- `--json` output is intended for chaining into other tools or agent steps

- FuelClock supply data and MBIE stock data are related but not identical, FuelClock applies its own live supply model on top of source data

- Geopolitical risk probabilities are market yes-prices from Polymarket-style data, not direct NZ fuel risk scores