On this page

aispot CLI

aispot is the scriptable client for Spot. It is a clap front-end over token-gateway-sdk: gateway calls go through BuyerClient, SellerClient, MarketClient, or health. Use it for a one-shot health check, a Chat Completions call, an OpenRouter savings report (analyze), seller ops from a shell, or the list of developer URLs.

If you are writing application code, the official SDKs present a typed interface — though they are not published yet, so the CLI and an OpenAI-compatible client are the options available today. If the app already speaks OpenAI Chat Completions, repoint the existing client.

The binary name is aispot. Do not look for a spot or aispot package on npm, PyPI, or Homebrew — those names belong to unrelated projects. aispot is not published to those registries.

Install

curl -fsSL https://aispotmarket.com/install.sh | sh

That one-liner installs aispot and runs aispot in the same terminal. If onboarding is unfinished, you get the three-step menu (switch to Spot, proxy when cheaper, last-month savings). It does not start OpenRouter. Pass other args after sh -s --:

curl -fsSL https://aispotmarket.com/install.sh | sh -s -- analyze vercel

The script detects your OS and architecture (linux / darwin × amd64 / arm64), downloads https://aispotmarket.com/cli/aispot-<os>-<arch>.tar.gz, and writes ~/.local/bin/aispot (or /usr/local/bin if writable).

Prebuilt binaries are currently published for linux-amd64 only. On other platforms the installer will not find an artifact; until more are published, use an OpenAI-compatible client or plain HTTP as described in Clients.

Check the install worked:

aispot health

Commands

Command	SDK call	Route
`aispot` / `aispot onboard`	stored credentials + `analyze` for step 3	Trade `/onboarding` equivalent
`aispot health`	`token_gateway_sdk::health`	`GET {base}/health`
`aispot chat --message TEXT`	`BuyerClient::chat_completions`	`POST /v1/chat/completions`
`aispot seller register`	`SellerClient::register`	`POST /v1/register`
`aispot seller ask`	`SellerClient::create_offer`	`POST /v1/offers`
`aispot seller cancel`	`SellerClient::cancel_offer`	`DELETE /v1/offers/{offer_id}`
`aispot seller capacity`	`SellerClient::report_capacity`	`POST /v1/capacity`
`aispot seller trades`	`SellerClient::list_trades`	`GET /v1/trades`
`aispot docs`	none (prints URLs)	—
`aispot openapi`	none (prints URL)	—
`aispot analyze openrouter`	`MarketClient` plus OpenRouter analytics	`GET /v1/markets`, candles, OpenRouter `POST /api/v1/analytics/query`
`aispot analyze vercel`	`MarketClient` plus Vercel AI Gateway	`GET /v1/markets`, candles, Vercel `GET /v1/report`
`aispot analyze cloudflare`	`MarketClient` plus Cloudflare AI Gateway	`GET /v1/markets`, candles, Cloudflare GraphQL `aiGatewayRequestsAdaptiveGroups`
`aispot analyze logout`	none	Deletes stored OpenRouter, Vercel, Cloudflare, and Spot keys

docs and openapi do not call the gateway. aispot docs is the recovery path for an agent that needs the developer index.

aispot with no subcommand and aispot onboard are the same three steps as Trade /onboarding. On a TTY you pick a numbered step. On a non-TTY the command prints the three options and how to run them (aispot onboard, aispot analyze openrouter). Completing a step stores onboarding_done next to credentials (AISPOT_CONFIG_DIR or the OS keyring). Skip is allowed; it is not a fourth outcome.

Point all inference at Spot — print the Spot URL and buyer token.
Proxy your current provider — collect provider + key. There is no live “sit in front of OpenRouter and fail over” API yet. What exists is max_price: Spot fills only when cheaper, otherwise 402.
Last-month savings — the existing analyze commands. After the report, the TTY menu offers steps 1 and 2. Analysis alone is a valid finish.

Environment

Variable / flag	Used by	Meaning
`--base-url` / `SPOT_API_URL`	buyer commands	Buyer API base. Default `https://aispotmarket.com/buy/api`.
`SPOT_SELLER_API_URL`	seller commands	Seller API base. Default `https://aispotmarket.com/sell/api`.
`--from-config` / `GATEWAY_CONFIG_URL`	discovery	`GET {url}/v1/config` → `gatewayApiUrl`. Mutually exclusive with `--base-url`.
`--api-key` / `SPOT_API_KEY` / `BUYER_API_KEY`	`chat`	Buyer Bearer key.
`--seller-key` / `SPOT_SELLER_KEY`	`seller ask`, `cancel`, `capacity`, `trades`	`X-Seller-API-Key`.
`OPENROUTER_API_KEY`	`analyze openrouter`	OpenRouter management key when not running interactively.
`VERCEL_AI_GATEWAY_API_KEY` / `AI_GATEWAY_API_KEY`	`analyze vercel`	Vercel AI Gateway API key (`vck_…`).
`CLOUDFLARE_API_TOKEN`	`analyze cloudflare`	Cloudflare dashboard API token (not a Workers AI inference key).
`CLOUDFLARE_ACCOUNT_ID`	`analyze cloudflare`	Cloudflare account tag.
`SPOT_API_KEY` / `BUYER_API_KEY`	`analyze`, `chat`	Spot buyer key. `analyze` stores one after you log in and paste it.
`SPOT_TRADE_URL` / `TRADE_URL`	`analyze`	Trade route to open for login. Default `http://localhost:8000` when the gateway is loopback, otherwise `https://aispotmarket.com/trade`.

aispot onboard
aispot health
aispot chat --message "hello" --model gpt-4 --max-price 0.05 --api-key "$SPOT_API_KEY"
aispot docs
aispot analyze openrouter
aispot analyze vercel
aispot analyze cloudflare
aispot seller register --name acme --endpoint http://127.0.0.1:9000/infer --model gpt-4 --region global --api-key sk-seller

aispot analyze openrouter|vercel|cloudflare asks for that provider's key, then opens the account login page (http://localhost:8000/account/login locally, or https://aispotmarket.com/account/login in production), asks you to paste a Spot buyer key, and stores both. There is no CLI OAuth for Spot yet. Start the local apex with ./start.sh if that page does not load. On a non-TTY, set the provider env vars and SPOT_API_KEY.

OpenRouter OAuth mints an inference key; if /analytics/meta returns 403 the command asks for a management key. Vercel custom reporting is Pro+ (403 says so). Cloudflare GraphQL has no USD field — spend is estimated from tokens.

See Clients, Authentication, Chat completions.