CH·02CLI reference

gpu watch list

List your watch rules

Synopsis

Lists the watch rules for your organization. Each row shows what the rule targets, what it alerts on, where the market is right now, whether the rule is armed or has already fired, and when it last fired.

The CURRENT column is the answer to "how close is this to firing?" — a target without a current reading is a number you have to go and check by hand. It is resolved from the public pricing catalog at display time:

For a price-under rule it is the cheapest per-GPU hourly rate matching the rule's dimensions. When that rate was divided out of a whole-node price, it is labelled — $1.76/GPU-hr (from an 8-GPU node) — because a per-GPU figure with no node context implies you can rent one GPU at that price, which for whole-node capacity is not true.
For an in-stock or count-at-least rule it is the number of units currently available across every matching offer.
sold out means we read the market and nothing on the rule's dimensions is obtainable. That is an observation you can act on.
A dash (—) means the market could not be read just now, or nothing exists on those dimensions at all. That is not the same as sold out, and neither is rendered as 0.

CURRENT is on-demand only

CURRENT counts and prices on-demand, in-stock offers only, and nothing else — because that is exactly what the alert evaluator looks at. A cheaper spot listing is not shown here, and it will not fire your rule either.

This matters when a spot price is below your threshold: if the column showed it, you would read a rule as overdue to fire that can never fire on that listing. The two filters are kept identical on purpose, so CURRENT versus your target is a real answer to "how close is this?" rather than a comparison against a market the rule cannot buy from.

In `-o json`

Each row is {"rule": …, "current": …}. The current object is omitted entirely when the market could not be read; when it is present, current.price_per_gpu_hour is nullable. The two absences mean different things:

`current`	`current.price_per_gpu_hour`	Meaning
absent	—	We could not read the market, or nothing matches these dimensions at all
present	`null`	We read the market and nothing is obtainable — sold out
present	a number	A price the rule could actually fire on

A script must not treat a null price as 0: the absence of an obtainable price is not a price of zero. current.node_gpu_count travels with the price so the per-GPU figure is never presented without the node it was divided out of, and current.available carries the unit count.

Unset dimensions render as any, not as a blank cell: a rule with no region filter is watching everywhere on purpose.

Results are paginated. When more rules remain, the CLI prints a Next cursor: hint to stderr (never stdout, so -o json output stays parseable); pass that value back via --cursor to fetch the next page. The cursor is an opaque token — copy it as-is rather than constructing one.

gpu watch list [flags]

Examples

# First page (50 rules by default)
gpu watch list

# Machine-readable, including the current market beside each target
gpu watch list -o json

# Continue from the opaque cursor printed on stderr by the previous call
gpu watch list --cursor "$NEXT_CURSOR" --limit 100

Options

      --cursor string   Pagination cursor from a previous list (see the stderr hint)
  -h, --help            help for list
      --limit int       Max rules to fetch (1-200) (default 50)

Options inherited from parent commands

      --api-base string   API base URL (override with GPUAI_API_BASE env) (default "https://api.gpu.ai/v1")
      --debug             Enable debug logging to stderr
  -o, --output string     Output format: table|json (default table on TTY, json otherwise)