fuelclock-nz

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

1. Run scripts/cli.py with the narrowest subcommand that answers the task
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:

python3 skills/fuelclock-nz/scripts/cli.py <command> [flags]

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:

python3 skills/fuelclock-nz/scripts/cli.py summary
python3 skills/fuelclock-nz/scripts/cli.py summary --json

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:

python3 skills/fuelclock-nz/scripts/cli.py watch
python3 skills/fuelclock-nz/scripts/cli.py watch --json

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:

python3 skills/fuelclock-nz/scripts/cli.py prices
python3 skills/fuelclock-nz/scripts/cli.py prices --fuel diesel
python3 skills/fuelclock-nz/scripts/cli.py prices --fuel 95 --json

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:

python3 skills/fuelclock-nz/scripts/cli.py supply
python3 skills/fuelclock-nz/scripts/cli.py supply --below-mso
python3 skills/fuelclock-nz/scripts/cli.py supply --fuel diesel --json

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:

python3 skills/fuelclock-nz/scripts/cli.py vessels
python3 skills/fuelclock-nz/scripts/cli.py vessels --flagged-only --limit 3
python3 skills/fuelclock-nz/scripts/cli.py vessels --fuel diesel --json

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:

python3 skills/fuelclock-nz/scripts/cli.py risk
python3 skills/fuelclock-nz/scripts/cli.py risk --limit 5
python3 skills/fuelclock-nz/scripts/cli.py risk --limit 3 --json

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:

python3 skills/fuelclock-nz/scripts/cli.py news
python3 skills/fuelclock-nz/scripts/cli.py news --limit 3
python3 skills/fuelclock-nz/scripts/cli.py news --limit 5 --json

Resources

• CLI entrypoint: scripts/cli.py
• Live smoke test: scripts/smoke_test.py

Notes

• No API key required
• Pure Python 3 standard library (urllib); no third-party dependencies
• 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

Source notes

Read references/source-notes.md for source ownership, access, and freshness boundaries.