Find and run a tool
Search the tools, read one's parameters and price, then run it.
Find
Describe the job in plain words:
supe find "exchange rates" frankfurter#rate Free exchange_rate
Next: supe inspect <tool_id>Each line is a tool id, its price per call and its tags. Narrow the list:
supe find --tag web_search # every tool with this tag
supe find --provider openalex # one provider's tools
supe find "transcribe audio" --max-price 20 # skip tools over 20 credits a call
supe find # every tagInspect
supe inspect frankfurter#ratefrankfurter#rate Free
Central bank reference rate for one currency pair, latest or on a past date back to 1948.
Tags: exchange_rate
Calls: GET /rate/{from}/{to}
Path (--path)
from string ISO 4217 code of the currency you have, e.g. "EUR".
to string ISO 4217 code of the currency you want, e.g. "USD".
Query (--query)
date? string YYYY-MM-DD for a past rate. Defaults to the latest.
Run: supe run frankfurter#rate --path from=… --path to=…Parameters are grouped by where they go: path, query or body. A ? means optional. Finding and inspecting are free.
Run
Give each parameter with the flag for its part:
supe run frankfurter#rate --path from=EUR --path to=USD
supe frankfurter#rate --path from=EUR --path to=USD # "run" is optional- Numbers,
true/falseand JSON are parsed; anything else is text. - Dots nest:
--body filter.country=USsends{"filter": {"country": "US"}}. - A parameter in the wrong part is refused with where it goes. supe never moves it for you:
supe: frankfurter#rate: 'from' goes in `path`, not `query`.For bigger input, pass the whole thing as JSON:
supe run serper#search --input '{"body": {"q": "lighthouses", "num": 5}}'
supe run serper#search -f input.json
cat input.json | supe run serper#search --input -The answer
The CLI prints the provider's response, then the tool, the cost and the receipt link. Add --full for everything as JSON:
{"status":"succeeded","tool_id":"frankfurter#rate","tags":["exchange_rate"],
"data":{"date":"2026-11-17","base":"EUR","quote":"USD","rate":1.1033},
"results":1,"cost":0,"unit":"credits","run_id":"run_c61f64885fcb", "...": "..."}Write large answers to a file so they stay out of the agent's context:
supe openalex#works_search --body query=agents -o out.json
# openalex#works_search · 1 credit · https://app.oex.sh/activity/run_a45b043e2757 · saved to out.jsonPrice caps
--max-price refuses a call that costs more, before it runs:
supe openalex#works_search --body query=agents --max-price 0
# {"error":{"code":"price_above_max","message":"openalex#works_search costs 1 credit, above max_price 0 credits."}}
# exit code 4Local files
A tool that takes a link also takes a local file. supe uploads it first (up to 20 MB):
supe fal#bria_background_remove --body image_url=./photo.pngThis works for parameters named *_url, *_urls, images and files. See Files.