spotinfo

name	spotinfo
description	Query Spot/preemptible VM prices, savings and interruption risk across AWS, GCP and Azure with the spotinfo CLI. Use this whenever the user asks which instance type is cheapest, what a Spot instance costs, what the interruption risk is, whether arm64 beats x86_64 on price, how AWS/GCP/Azure Spot pricing compares, or wants to size a workload to a budget — including when they describe the need without naming spotinfo ("find me a cheap 8-core box", "least interruption-prone instance for a CI runner", "compare spot prices across clouds"). It answers offline with no cloud credentials in about 40ms, so prefer it over guessing prices from memory, scraping a pricing page, or writing throwaway SDK code.
license	Apache-2.0
compatibility	Requires the spotinfo binary on PATH (brew install alexei-led/tap/spotinfo, or ghcr.io/alexei-led/spotinfo). jq is needed only for scripts/compare-clouds.sh. No cloud credentials and no network are required.
metadata	{"author":"alexei-led","version":"3.0.0","repository":"https://github.com/alexei-led/spotinfo"}

spotinfo

One binary that answers two questions about Spot/preemptible VMs on AWS, GCP and Azure:

• "What is there?" → spotinfo list — requires nothing, shows every match
• "What should I run?" → spotinfo recommend — requires --architecture, --min-vcpu and --min-memory-gib, returns a ranked page

Pick recommend when the user states a requirement ("I need 8 cores and 32 GB"). Pick list when they want to see what exists ("what do m5 instances cost").

It ships an embedded price snapshot per cloud, so it answers with no credentials and no network. A query is free and cannot fail on missing auth — run it instead of guessing a price from memory.

Two habits

Pass --offline unless the user needs today's price. It answers from the snapshot in about 40 ms and makes no network call. Without it, --region all (the default) queries every AWS region and takes seconds.

Pass --output json whenever you will parse the result. table is for people to read.

spotinfo recommend --cloud aws --offline --output json \
  --architecture x86_64 --min-vcpu 8 --min-memory-gib 32 --top 5

Three things that will break a parser

The row key differs by command. list puts rows under candidates, recommend under recommendations. The documents otherwise look alike, so a parser written for one silently finds nothing in the other.

Prices are strings. "0.047500000" is fixed-point on purpose, because a float drifts on the last digit. Call tonumber before you compare or total. On list the field is nullable — AWS omits some machines from its price feed, and those carry null rather than 0.

risk is always an object, even when empty. Read risk.status first.

Full field reference: references/output-schema.md.

unavailable is not zero

On AWS, risk carries a real Spot Advisor measurement. On GCP and Azure every field except status is null:

"risk": { "status": "unavailable", "kind": null, "label": null }

That means the vendor does not publish the figure. It does not mean the risk is low, and it does not mean zero. Reading risk.label unconditionally gives you null, which prints as an empty cell and reads to a person as "fine".

When you report a GCP or Azure machine, say the cloud publishes no interruption figure. Quietly dropping the column is how someone puts a database on a preemptible VM.

This is also why the risk-capped workloads are AWS-only — the web, ci and batch ceilings are AWS Spot Advisor bucket boundaries:

spotinfo recommend --cloud aws --workload web  --offline --architecture x86_64 --min-vcpu 4 --min-memory-gib 16
spotinfo recommend --cloud gcp --workload cost --offline --architecture x86_64 --min-vcpu 4 --min-memory-gib 16

--workload cost is the default, makes no interruption claim, and answers everywhere.

Per-cloud capabilities and limits: references/clouds.md.

Flags that matter

Flag	Note
--cloud aws|gcp|azure	Defaults to aws. Set it whenever the user named a cloud.
--offline	Snapshot only, no network. Use by default.
--machine	An RE2 regexp, not a glob. '^m5\.', never 'm5*'. Anchor it or m5dn matches too.
--region	Repeatable. Defaults to all. Scope it when the user named a region.
--sort / --order	machine|price|region|risk|savings|score, asc|desc.
--max-price	USD per machine-hour ceiling.
--os linux|windows	AWS and Azure serve both. GCP refuses Windows.
--top	recommend only, maximum 50.

When it refuses

spotinfo refuses a flag it cannot honour instead of ignoring it. Exit is non-zero with empty stdout, so branch on the exit code and read stderr — the message names the flag, the cloud and the limit, and usually names the fix.

You ran	It says
--os windows --cloud gcp	Google publishes Linux Spot prices only
--workload web on GCP/Azure	no comparable interruption figure — use --workload cost
--sort score without --with-score	only --with-score fetches the figures the sort orders
--with-score --offline	no snapshot carries a placement figure
--cpu, --memory, --type, --price	retired names — the hint gives the replacement

Recipes

Common tasks with commands and result handling: references/recipes.md.

To compare one requirement across all three clouds in a single table:

scripts/compare-clouds.sh --min-vcpu 4 --min-memory-gib 16 --offline

Machine naming differs per cloud, so there is no single cross-cloud query — the script runs one recommend per cloud and merges the output.

MCP server

spotinfo --mcp speaks MCP 2025-11-25 over stdio with three read-only tools: list_spot_machines, recommend_spot_machines, list_cloud_regions. Argument names mirror the flags mechanically (--min-vcpu → min_vcpu, --region → regions, an array).

If you already have shell access, prefer the CLI — one call, same schema, and you can pipe it.

Reporting to the user

Give price, savings percent and risk together. A cheap machine with a >20% interruption rate is a different recommendation from a cheap stable one, and the price alone hides that. When risk is unavailable, say the cloud does not publish it — never let silence read as safety.