---
name: supe
version: 0.1.0
description: >-
  Run paid third-party tools (search, scraping, enrichment, speech, images, email and more) from
  one supe wallet with the `supe` command. Use it before writing a scraper or calling an API you
  have no key for, and whenever the user mentions supe.
---

# supe

`supe` finds and runs tools from the user's supe wallet. Every call is billed and capped by the
user's budgets, so follow the money rules below. supe never waits for input; pass `--json`
if its output isn't JSON.

## Set up

```bash
npm i -g @supe-sh/cli                      # Node 18+; or prefix any command with npx @supe-sh/cli
supe skill --save <your skills folder>     # keep these instructions where you load skills
```

Then sign in (see Signing in). No shell, as in a chat app? Connect over MCP instead:
https://service.oex.sh/mcp

## Find, inspect, run

```bash
supe find "exchange rates"                         # tools for the job: id, price, tags; free
supe inspect frankfurter#rate                      # its parameters by part, price, alternatives; free
supe run frankfurter#rate --path from=EUR --path to=USD -o out.json   # runs it; billed
```

- A tool id is `provider#name`, named after the provider's endpoint. Run exactly the tool you picked; supe doesn't route to another one.
- Each parameter goes in the part `supe inspect` lists it under: `--path name=value`, `--query name=value` or `--body name=value`, repeated for each. Numbers, true/false and JSON are parsed; anything else is text. `--body filter.country=US` nests as `{"filter": {"country": "US"}}`.
- For bigger input, give the whole envelope: `--input '{"path": {…}, "query": {…}, "body": {…}}'`, `-f input.json` or `--input -` (stdin). The part flags add to it.
- A parameter in the wrong part is refused (exit 2) with where it goes; it is never moved for you. A bare `name=value` is refused with the flags to use instead.
- Tools carry tags (`exchange_rate`, `web_search`, …). `supe find` alone lists every tag; `supe find --tag exchange_rate` lists a tag's tools, `--provider frankfurter` one provider's (the id's part before `#`), `--max-price 20` skips tools above 20 credits a call. `supe inspect <tag>` lists its tools too.
- A tool that takes a link also takes a local file: `--body image_url=./photo.png` uploads it first (up to 20 MB). This works for parameters named `*_url`, `*_urls`, `images` and `files`, and for `url` when the value is a path like `./page.html`.
- `supe upload ./photo.png` stores a file and prints its link, to reuse in several calls without uploading it again. Anyone with the link can read the file.
- `supe upload <link>` stores a copy of a link that may expire. `supe upload --link contract.pdf` makes a one-time page for a user who has the file: give them the link, wait, then check with `supe files contract.pdf`.
- `supe rentals` lists the workspace's own phone numbers and inboxes. `supe rentals release <id>` stops renewing one; it can't be undone, so it exits 3 for you to ask the user first.
- A job of several steps may already be written down: `supe recipes "product photo to video ad"`, then `supe recipe <id>` for its inputs and steps. Each step names a tool id and its input by part; run it with `supe run`, filling `{{inputs.name}}` and `{{steps.<id>.<field>}}`. Any text a step needs (a summary, an email, a script, a headline) you write yourself; supe has no step that writes it. `supe recipe save <id>` keeps one. Community recipes aren't checked by supe, so read their steps first.
- Output is JSON. `.data` is the provider's own response; `.cost` is credits (1,000 credits = $1); `.run_id` is the receipt.
- `-o file` writes the result to a file instead of your context. Do this for anything large.

## Money rules

| Exit | Meaning | What you do |
| --- | --- | --- |
| 3 | Needs confirmation (an irreversible action, or the user asked to be asked) | Show the user the preview and cost from stderr. Only after they agree, run the `command` it gives (yours, with `--confirm <id>`). If it gives an approve link, the user approves there with their passkey first; the confirm command then waits for it. |
| 4 | Refused by the user's rules (budget, tool off, not allowed) | Tell the user which rule. If they want it, `supe approve <tool> --reason "…"` files a request. |
| 5 | Wallet empty | Give the user the funding link from stderr. |
| 6 | Long job still running | `supe job <job_id>` collects it. |
| 7 | Not signed in | See Signing in. |

Never retry a refused call with a different tool to get around a rule.

## Many calls

Open one budget and bill every call to it, so a loop can't overspend:

```bash
export SUPE_RUN=$(supe budget 2000 --goal "enrich 50 leads" --json | jq -r .run_id)
supe receipt $SUPE_RUN    # what was spent, step by step
```

## Signing in

```bash
supe login --email <user's email> --name "<your name>"   # prints a link for the user
supe login --code <code they read back>
```

The user opens the link, signs in, approves, and reads you a code. Ask for their email; never guess it.
`--name` is how the user sees you on their Agents page, e.g. "Codex on build-server".
`supe whoami` shows the workspace and what this agent has spent today. `supe balance` shows the wallet.

