Skip to Content
supedocs

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 tag

Inspect

supe inspect frankfurter#rate
frankfurter#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/false and JSON are parsed; anything else is text.
  • Dots nest: --body filter.country=US sends {"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.json

Price 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 4

Local 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.png

This works for parameters named *_url, *_urls, images and files. See Files.

On this page