# supe docs

Quick facts for agents:

- Fastest setup for an agent with a shell: read https://oex.sh/SKILL.md and follow it. It installs the `supe` CLI (`npm i -g @supe-sh/cli`) and signs in with `supe login --email <user's email>`.
- No shell: MCP at https://service.oex.sh/mcp (Streamable HTTP, OAuth or `Authorization: Bearer <key>`).
- Code: HTTP API at https://service.oex.sh/v1, `Authorization: Bearer <key>`, contract at https://service.oex.sh/v1/openapi.json.
- The loop: find a tool (free), inspect it (free), run it (billed). Tool ids are `provider#name`. Input is `{path, query, body}`.
- Prices are in credits: 1,000 credits = $1. A failed call is never charged.
- Actions that can't be undone wait for the user's yes (CLI exit 3, HTTP 409 needs_confirmation). Never pass a confirmation the user hasn't agreed to.
- A refusal by the user's rules is an answer, not an error. Tell the user; never retry with another tool to get around it.
- Every page below is Markdown at its URL plus `.md`. All pages in one file: /llms-full.txt

# HTTP API (/connect/api)

The API is for programs: plain HTTP, stable error codes, and the same tools, rules and receipts as the CLI and MCP.

| | |
|---|---|
| Base URL | `https://service.oex.sh/v1` |
| Auth | `Authorization: Bearer <key>` |
| Contract | [`/v1/openapi.json`](https://service.oex.sh/v1/openapi.json) |

## Get a key [#get-a-key]

On the dashboard, open **Agents → Get an API key → Make a key**. You see the key once.

- `oex_live_...` keys make real calls and spend credits.
- `oex_test_...` keys return sample data and cost nothing. Use one while you wire things up.

## Your first call [#your-first-call]

```bash
curl -s https://service.oex.sh/v1/run \
  -H "Authorization: Bearer $SUPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool": "frankfurter#rate", "input": {"path": {"from": "EUR", "to": "USD"}}}'
```

```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",
  "test": false,
  "latency_ms": 66,
  "receipt_url": "https://app.oex.sh/activity/run_c61f64885fcb"
}
```

`data` is the provider's own response. `cost` is in credits (1,000 credits are $1).

## Find the tool first [#find-the-tool-first]

```bash
curl -s "https://service.oex.sh/v1/tools?query=exchange%20rates" -H "Authorization: Bearer $SUPE_API_KEY"
curl -s "https://service.oex.sh/v1/tools/frankfurter%23rate" -H "Authorization: Bearer $SUPE_API_KEY"
```

The first lists matching tools with their price and tags. The second gives one tool's parameters by part (`path`, `query`, `body`). Encode the `#` in a tool id as `%23`.

## Retries [#retries]

Send an `Idempotency-Key` header with any unique value. A retry with the same key and body returns the first answer instead of running again, for 24 hours, so a network blip never pays twice.

Every endpoint is in the [HTTP API reference](/reference/http-api), and every error in [Errors and exit codes](/reference/errors).

# MCP (/connect/mcp)

Use MCP when your agent has no shell. If it can run commands, the [skill](/connect/skill) is simpler and does more.

| | |
|---|---|
| Server URL | `https://service.oex.sh/mcp` |
| Transport | Streamable HTTP |
| Sign-in | OAuth in the browser, the first time you use it. Or send an API key as `Authorization: Bearer <key>`. |

Each app that signs in shows up as its own agent on your dashboard's Agents page, with its own spending and limits.

## Add it to your app [#add-it-to-your-app]

Pick your app. Each tab has the OAuth way first, then the API key way for when you can't sign in from the app (a server, CI, or a shared machine).

<Tabs items={["Claude Code","Claude app","ChatGPT","Cursor","Codex","VS Code","Gemini CLI","Other"]}>
<Tab value="Claude Code">
Run this in a terminal:

```bash
claude mcp add --transport http supe https://service.oex.sh/mcp
```

Then type `/mcp` inside Claude Code, pick **supe** and sign in. Add `--scope user` to use it in every project, or `--scope project` to share it through the repo's `.mcp.json`.

With an API key instead:

```bash
claude mcp add --transport http supe https://service.oex.sh/mcp \
  --header "Authorization: Bearer $SUPE_API_KEY"
```
</Tab>

<Tab value="Claude app">
Works in Claude on the web, desktop and mobile, set up once.

1. Open **Customize**, then **Connectors**.
2. Choose **Add**, then **Add custom connector**, and name it `supe`.
3. Paste `https://service.oex.sh/mcp` as the URL and choose **Connect**, then sign in.

On a Team or Enterprise plan, an owner adds the connector under **Organization settings → Connectors** first; members then connect it from **Customize → Connectors**.
</Tab>

<Tab value="ChatGPT">
Needs a paid plan. Set it up on chatgpt.com; the desktop app can use it after.

1. Open **Settings → Apps → Advanced settings**.
2. Turn on **Developer mode** and choose **Create app**.
3. Paste `https://service.oex.sh/mcp`, pick **OAuth**, and sign in.
</Tab>

<Tab value="Cursor">
Add this to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "supe": {
      "url": "https://service.oex.sh/mcp"
    }
  }
}
```

Cursor asks you to sign in the first time it uses supe.

With an API key instead, kept in an environment variable:

```json
{
  "mcpServers": {
    "supe": {
      "url": "https://service.oex.sh/mcp",
      "headers": { "Authorization": "Bearer ${env:SUPE_API_KEY}" }
    }
  }
}
```
</Tab>

<Tab value="Codex">
```bash
codex mcp add supe --url https://service.oex.sh/mcp
codex mcp login supe
```

The second line opens the sign-in in your browser.

With an API key instead, add this to `~/.codex/config.toml` and set `SUPE_API_KEY` in your environment:

```toml
[mcp_servers.supe]
url = "https://service.oex.sh/mcp"
bearer_token_env_var = "SUPE_API_KEY"
```
</Tab>

<Tab value="VS Code">
Run **MCP: Add Server** from the command palette, choose **HTTP**, paste `https://service.oex.sh/mcp` and name it `supe`. VS Code opens the sign-in the first time Copilot uses it.

Or add it to `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "supe": {
      "type": "http",
      "url": "https://service.oex.sh/mcp"
    }
  }
}
```

With an API key instead, add `"headers": { "Authorization": "Bearer ${input:supe-key}" }` to the server, and VS Code asks for the key once.
</Tab>

<Tab value="Gemini CLI">
Add this to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "supe": {
      "httpUrl": "https://service.oex.sh/mcp"
    }
  }
}
```

Then run `/mcp auth supe` inside Gemini CLI to sign in. Use `httpUrl`, not `url`: `url` is for the older SSE transport.

With an API key instead, add `"headers": { "Authorization": "Bearer <your key>" }` to the server.
</Tab>

<Tab value="Other">
Any client that speaks MCP over Streamable HTTP works:

- URL: `https://service.oex.sh/mcp`
- Auth: OAuth (the server advertises it, so the client finds the sign-in itself), or the header `Authorization: Bearer <key>`.

To check a key by hand:

```bash
curl -s https://service.oex.sh/mcp \
  -H "Authorization: Bearer $SUPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
</Tab>
</Tabs>

Get an API key from the dashboard: **Agents → Get an API key → Make a key**. You see the key once.

## Check it works [#check-it-works]

Ask your agent: **"What's my supe balance?"** It should call `wallet_balance` and tell you the number of credits. Then try something real, like "find a tool that gets exchange rates and get today's euro to dollar rate".

## What the agent can do [#what-the-agent-can-do]

The agent sees [15 tools](/reference/mcp-tools): it finds a tool with `find_tool`, reads its parameters with `inspect_tool`, and runs it with `execute_tool`. The server also sends the agent instructions on money, confirmations and long jobs, so you don't need to paste any.

## If something's off [#if-somethings-off]

- **The app never asks you to sign in.** Remove supe and add it again, or use the API key way.
- **The agent says a call was refused.** That's one of your [limits](/controls/limits) working. The refusal names the rule; change it on the dashboard if you want the call to go through.
- **"Not signed in" after a while.** Sign in again from the app (`/mcp` in Claude Code, `codex mcp login supe` in Codex).

# Skill and CLI (/connect/skill)

<SetupLine>
Set up supe using https://oex.sh/SKILL.md
</SetupLine>

Paste that into your agent. [SKILL.md](https://oex.sh/SKILL.md) is a short guide written for agents: how to install `supe`, find and run tools, follow your money rules, and sign in. Your agent reads it, sets itself up, and keeps the guide where it loads skills.

This works with any agent that can run commands: Claude Code, Codex, Cursor's agent, Gemini CLI, your own scripts.

## Why the CLI [#why-the-cli]

- **It never waits for input.** Every command finishes on its own and says what happened with an [exit code](/reference/errors), so an agent can't get stuck on a prompt.
- **Big results go to files.** `-o out.json` keeps a large answer out of the agent's context.
- **Local files just work.** A tool that wants a link to an image also takes `./photo.png`; supe uploads it first.
- **It reads like a person would type it.** `supe frankfurter#rate --path from=EUR --path to=USD`.

## Install by hand [#install-by-hand]

```bash
npm i -g @supe-sh/cli          # Node 18 or later
supe skill --save ~/.claude/skills
```

`supe skill --save <dir>` writes `<dir>/supe/SKILL.md`. Point it at the folder your agent loads skills from. To try it without installing, put `npx @supe-sh/cli` in front of any command.

## Sign in [#sign-in]

Sign-in takes two commands, so it never blocks:

```bash
supe login --email you@example.com --name "Codex on build-server"
supe login --code 123456
```

The first prints a link. You open it, sign in and approve, and the page shows a code for the second command. `--name` is how you'll see this agent on the Agents page.

Check it:

```bash
supe whoami     # the workspace, this agent, and what it spent today
supe balance    # the wallet, in credits
```

## Several agents on one machine [#several-agents-on-one-machine]

Each `supe login` adds an agent. `supe agents` lists them; `--agent <name>` (or `SUPE_AGENT`) picks one for a command. `supe logout` revokes the current one.

## In CI or a server [#in-ci-or-a-server]

Skip the sign-in and use a key from the dashboard (**Agents → Get an API key**):

```bash
export SUPE_API_KEY=oex_live_...
supe run frankfurter#rate --path from=EUR --path to=USD
```

| Variable | What it does |
|---|---|
| `SUPE_API_KEY` | A dashboard key, used instead of a signed-in agent |
| `SUPE_RUN` | Bill every call to this run ([Runs and budgets](/use/runs-and-budgets)) |
| `SUPE_AGENT` | Act as this signed-in agent |
| `SUPE_BASE_URL` | Another server |
| `SUPE_CONFIG_DIR` | Where sign-ins are kept |

Every command is in the [CLI reference](/reference/cli).

# Approvals (/controls/approvals)

When a rule stops an agent, it doesn't work around it. It asks you. Requests wait on the dashboard under **Approvals**, and you get an email.

## What agents ask for [#what-agents-ask-for]

| Request | When | If you say yes |
|---|---|---|
| A tool that's off | The agent needs a tool you switched off or didn't give it | The tool is turned on for it |
| More budget | A budget is used up | The budget goes up by the amount asked |
| Your Face ID | A confirmation needs your passkey | That one call goes ahead |

Each request shows which agent asked, why, and the amount. An admin can approve any of them; one that needs Face ID needs a passkey.

## How an agent asks [#how-an-agent-asks]

```bash
supe approve exa#search --reason "the user wants web results with page text"
supe approve exa#search --reason "50 more leads" --amount 2000
```

Over HTTP: `POST /v1/approvals` with `{"kind": "tool_access" or "budget", "tool_id", "reason", "amount"}`. Over MCP: `request_approval`.

Then the agent tells you what it asked for and waits for you. It never retries the call with another tool to get past the rule.

# Limits (/controls/limits)

Limits live on the [dashboard](https://app.oex.sh) under **Controls**. Every call from every agent is checked against them before it runs, whichever way the agent connects. A refused call costs nothing and says which rule refused it.

## Budgets [#budgets]

A budget caps spending for one thing over one period.

| For | Caps |
|---|---|
| Whole workspace | everything every agent spends |
| An agent | one agent's spending |
| A tag | every tool with that tag, like `web_search` |
| A provider | every tool from one provider |
| A tool | one tool |

| Period | Means |
|---|---|
| per call | no single call may cost more |
| a day, a month | resets each day or month |
| in total | never resets |

Add one under **Controls → Budgets → Add**. A call over a budget is refused with `limit_reached`. The agent can [ask you](/controls/approvals) to raise it.

## Ask me first [#ask-me-first]

**Controls → Rules → Ask me for anything over** sets an amount in credits. Any call that costs more waits for your yes, like an action that can't be undone does. Leave it empty to be asked only about things that can't be undone. See [Confirmations](/use/confirmations).

## Face ID [#face-id]

**Approve with Face ID** decides when a yes in chat isn't enough and your passkey is needed: Off, Permanent (things that can't be undone) or Everything I'm asked. Add a passkey under Settings first.

## Which tools [#which-tools]

- **Tools** lists every tool. Turn one off and no agent can call it. Pin the ones you prefer; they're marked as your pick when an agent searches.
- **Agents → an agent → Tools it may use** limits that agent to some tags, providers or tools.

A call to a tool that's off is refused with `tool_disabled` or `tool_not_allowed`. The agent can ask you to turn it on.

## Pause all spending [#pause-all-spending]

**Controls → Pause all spending** stops every agent right away: paid and free calls are refused with `workspace_frozen` until you turn it back on. Nothing else changes.

## Who can change limits [#who-can-change-limits]

Owners and admins change budgets, rules, Face ID and the pause. Owners, admins and developers can turn tools on and off. Everyone else can look.

# Wallet and credits (/controls/wallet)

Your workspace has one wallet. Every agent spends from it, and every call shows its price in credits before it runs.

**1,000 credits = $1.** A 3-credit search costs a third of a cent.

## Add credits [#add-credits]

On the dashboard, open **Wallet** and add between $5 and $1,000 by card. Save the card to turn on **auto top-up**: when the balance drops under an amount you set, supe adds credits, up to a monthly cap you choose.

## What you're charged [#what-youre-charged]

- The price is **held** while a call runs and **charged** only when it succeeds.
- **A failed call costs nothing.** Neither does finding or inspecting a tool.
- Some tools are priced per result. The answer's `results` says how many were counted.
- A rented phone number or inbox costs its price the first month, then the same each month until you release it.

## Check the balance [#check-the-balance]

```bash
supe balance
```

```text
99,999 credits available
```

Over HTTP, `GET /v1/wallet` returns `balance`, `held` (in calls still running) and `available`. Over MCP, `wallet_balance`.

## When it runs out [#when-it-runs-out]

A call the balance can't cover is refused with `insufficient_balance` (exit 5) and a link to add credits. You also get an email when the balance runs low.

## Rentals [#rentals]

Phone numbers and inboxes your agents rent belong to your workspace:

```bash
supe rentals                 # what's rented, the monthly price, when each renews
supe rentals release <id>    # stop renewing one; it can't be undone, so it asks first
```

A released rental keeps working until the date it's paid through.

# Webhooks (/controls/webhooks)

Add a webhook under **Settings → Webhooks**: a URL and the events to send it. You see its signing secret once.

## Events [#events]

| Event | When |
|---|---|
| `approval.requested` | An agent asks for a tool, more budget or your Face ID |
| `budget.reached` | A budget is used up |
| `balance.low` | The wallet is running low |
| `topup.succeeded` | Credits were added |
| `topup.failed` | Adding credits failed |
| `workspace.frozen` | Someone paused all spending |
| `agent.connected` | A new agent signed in |
| `price.changed` | A tool's price changed |
| `tool.added` | A new tool is available |
| `rental.unpaid` | A rental couldn't be renewed |
| `rental.ended` | A rental ended |

## The request [#the-request]

supe sends a `POST` with a JSON body:

```json
{
  "id": "evt_3f2a9c1d7b6e4a10",
  "type": "budget.reached",
  "workspace": "ws_f40897a04dc54038",
  "created_at": 1794901160.25,
  "title": "…",
  "body": "…",
  "data": {}
}
```

Headers: `X-OEX-Event` is the event type, `X-OEX-Signature` is `sha256=` followed by the HMAC-SHA256 of the raw body, keyed with your signing secret.

## Check the signature [#check-the-signature]

Compute the HMAC over the raw body before you parse it:

<Tabs items={["Node","Python"]}>
<Tab value="Node">
```js
import { createHmac, timingSafeEqual } from 'node:crypto';

function isFromSupe(rawBody, header, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  return header.length === expected.length && timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}
```
</Tab>

<Tab value="Python">
```python
import hashlib, hmac

def is_from_supe(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(header, expected)
```
</Tab>
</Tabs>

Send a test event from the webhook's menu on the dashboard to check your endpoint.

# How it works (/how-it-works)

## Tools [#tools]

A tool is one provider's endpoint, like `frankfurter#rate` or `openalex#works_search`. Its id is `provider#name`. supe has 2,000+ of them: search, scraping, people and company data, email, SMS, calls, images, video, speech and more.

Every tool has:

- **Tags** that say what job it does, like `exchange_rate` or `web_search`. Tools that share a tag do similar jobs, but each takes its own parameters.
- **A price** per call, shown before you run it. Many tools are free.
- **Parameters** grouped by where they go in the request: `path`, `query` or `body`.

Your agent runs exactly the tool it picked. supe never swaps in a different one behind its back.

## The loop [#the-loop]

1. **Find.** Search by the job in plain words: `supe find "exchange rates"`. Free.
2. **Inspect.** Read one tool's parameters and price: `supe inspect frankfurter#rate`. Free.
3. **Run.** Call it with its parameters: `supe run frankfurter#rate --path from=EUR --path to=USD`. Billed.

The answer is the provider's own response, unchanged.

## Credits [#credits]

Everything is priced in credits. **1,000 credits are $1.** Your workspace has one prepaid balance that every agent spends from. A call's price is held while it runs and charged only if it succeeds: **a call that fails costs nothing**.

## Runs [#runs]

Every paid call belongs to a run: a budget ceiling and one receipt. A run for a single call opens on its own. For a job of many calls, open one run with a budget and bill every call to it, so a loop can't overspend. See [Runs and budgets](/use/runs-and-budgets).

## Your rules [#your-rules]

Before any call runs, supe checks it against the rules you set on the dashboard:

- [Limits](/controls/limits): budgets for the workspace, an agent, a tag, a provider or one tool, by call, day, month or in total.
- Tool switches: turn off tools you don't want used, or give an agent only some tools.
- [Confirmations](/use/confirmations): anything that can't be undone, like sending an email, waits for your yes. You can require Face ID for it.
- Pause: one button stops all spending.

A refused call says which rule refused it. The agent tells you, and can [ask for an exception](/controls/approvals) instead of working around it.

## Ways in [#ways-in]

The same tools, rules and receipts apply whichever way your agent connects: the [CLI](/connect/skill), [MCP](/connect/mcp) or the [HTTP API](/connect/api).

# Introduction (/)

<SetupLine>
Set up supe using https://oex.sh/SKILL.md
</SetupLine>

That line is the whole setup. Your agent reads the skill, installs the `supe` command, and asks you to sign in once. From then on it can find a tool for the job, see its price, and run it, billed to your supe wallet.

## What your agent gets [#what-your-agent-gets]

Search, scraping, people and company data, email, SMS, phone calls, images, video, speech and more: 2,000+ tools, each one a provider's own endpoint. There is no signup or API key per provider. Finding and reading a tool is free; a call that fails is never charged.

## What you keep [#what-you-keep]

Every paid call goes through your rules first. You set budgets per agent, per tool or for the whole workspace. Anything that can't be undone, like sending an email, waits for your yes, and you can require Face ID for it. One button pauses all spending.

## Ways to connect [#ways-to-connect]

<Cards>
<Card title="Skill and CLI" href="/connect/skill" description="Recommended. For any agent with a shell: Claude Code, Codex, Cursor, scripts." />

<Card title="MCP" href="/connect/mcp" description="For chat apps without a shell: Claude, ChatGPT." />

<Card title="HTTP API" href="/connect/api" description="For your own code, with an API key." />
</Cards>

## For agents [#for-agents]

These docs are plain Markdown underneath. [`/llms.txt`](/llms.txt) lists every page, [`/llms-full.txt`](/llms-full.txt) is all of them in one file, and any page's URL with `.md` added returns its Markdown.

# Quickstart (/quickstart)

<Steps>
<Step>
### Give your agent the skill [#give-your-agent-the-skill]

Paste this into Claude Code, Codex, Cursor or any agent that can run commands:

<SetupLine>
Set up supe using https://oex.sh/SKILL.md
</SetupLine>

The agent installs the CLI and saves the instructions where it keeps skills, for example:

```bash
npm i -g @supe-sh/cli
supe skill --save ~/.claude/skills
```

No shell, as in the Claude or ChatGPT app? Use [MCP](/connect/mcp) instead and skip to step 3.
</Step>

<Step>
### Approve the sign-in [#approve-the-sign-in]

The agent asks for your email and starts a sign-in:

```bash
supe login --email you@example.com --name "Claude Code on my laptop"
```

Open the link it prints, sign in, and approve. The page shows a code: read it back to your agent, which finishes with `supe login --code <code>`. The agent now appears on your dashboard's Agents page under the name it gave.
</Step>

<Step>
### Add credits [#add-credits]

Open **Wallet** on the [dashboard](https://app.oex.sh) and add credits. 1,000 credits are $1. Many tools are free; you only need credits for paid ones.
</Step>

<Step>
### Ask for something [#ask-for-something]

Ask your agent for anything a tool can do, such as "what's the euro to dollar rate today?". It finds a tool, reads it, and runs it:

```bash
supe find "exchange rates"
supe inspect frankfurter#rate
supe run frankfurter#rate --path from=EUR --path to=USD
```

The last command prints the provider's answer, then the tool, the cost and a link to the receipt:

```text
{
  "date": "2026-11-17",
  "base": "EUR",
  "quote": "USD",
  "rate": 1.1033
}
frankfurter#rate · 0 credits · https://app.oex.sh/activity/run_58f5f2fbc4f0
```

The call is on the dashboard's Activity page too.
</Step>
</Steps>

## Next [#next]

- Set [limits](/controls/limits) before an agent runs anything expensive.
- Read [how it works](/how-it-works): tools, runs, credits and confirmations in one page.

# CLI (/reference/cli)

```bash
npm i -g @supe-sh/cli    # Node 18 or later
```

The CLI never waits for input. Output is JSON when it isn't writing to a terminal, or with `--json`. Every command ends with an [exit code](/reference/errors#exit-codes).

## Tools [#tools]

| Command | What it does |
|---|---|
| `supe find [words]` | Search tools. `--tag`, `--provider`, `--max-price`, `--limit` filter. Alone, lists every tag. |
| `supe inspect <tool_id\|tag>` | A tool's parameters by part, price and alternatives; or a tag's tools |
| `supe run <tool_id> …` | Run one tool. `supe <tool_id> …` does the same. |
| `supe job <job_id>` | Collect a [long job](/use/long-jobs) |
| `supe upload <file\|link>` | Store a local file, or a copy of a link, and print its link |
| `supe upload --link <name>` | A one-time page for a person to upload a file through |
| `supe files [name]` | Files in this workspace, with their links |

## Recipes [#recipes]

| Command | What it does |
|---|---|
| `supe recipes [words]` | Search the Cookbook and yours; with no words, list yours |
| `supe recipe <id> [--tier t]` | Its inputs and steps |
| `supe recipe save <id>` | Copy a Cookbook recipe into your workspace |
| `supe recipe save -f <file>` | Write one from JSON: name, description, inputs, steps |

## Money [#money]

| Command | What it does |
|---|---|
| `supe balance` | The wallet, in credits |
| `supe budget <credits>` | Open a run with a spending cap; bill calls to it with `SUPE_RUN` |
| `supe runs` | Recent runs |
| `supe receipt <run_id>` | What a run spent, step by step |
| `supe approve <tool> --reason "…"` | Ask a person to turn a tool on; `--amount` asks for more budget |
| `supe rentals` | Phone numbers and inboxes this workspace rents |
| `supe rentals release <id>` | Stop renewing one. It can't be undone, so it asks first (exit 3). |

## Account [#account]

| Command | What it does |
|---|---|
| `supe login --email <email> [--name <name>]` | Start signing in this machine as an agent; prints a link for your user |
| `supe login --code <code>` | Finish signing in with the code the page shows |
| `supe logout` | Revoke this agent and forget it here |
| `supe whoami` | The workspace, this agent and what it spent today |
| `supe agents` | Agents signed in on this machine |
| `supe skill [--save <dir>]` | Print the agent instructions; `--save` writes `<dir>/supe/SKILL.md` |

## Run options [#run-options]

| Flag | What it does |
|---|---|
| `--path name=value` | A path parameter. Repeat for each. |
| `--query name=value` | A query parameter |
| `--body name=value` | A body parameter. `a.b=1` nests as `{"a":{"b":1}}`. |
| `--input <json\|->`, `-f <file>` | The whole input as `{"path":…,"query":…,"body":…}`; the flags above add to it |
| `--max-price <credits>` | Refuse the call if it costs more |
| `--budget <credits>` | Cap the run this call opens |
| `--run <id>` | Bill an open run (or set `SUPE_RUN`) |
| `--goal <text>` | What the run is for, shown on its receipt |
| `--confirm <id>` | Go ahead with a call that asked first |
| `--no-wait` | Return a long job's id instead of waiting |
| `-o <file>` | Write the result to a file |
| `--full` | The whole answer (cost, run, receipt), not just the provider's response |

## Everywhere [#everywhere]

| Flag or variable | What it does |
|---|---|
| `--json` | JSON on stdout (the default without a terminal) |
| `--agent <name>`, `SUPE_AGENT` | Act as this signed-in agent |
| `SUPE_API_KEY` | Use a dashboard key instead of a signed-in agent, as in CI |
| `--base-url <url>`, `SUPE_BASE_URL` | Another server |
| `SUPE_CONFIG_DIR` | Where sign-ins are kept |
| `--help`, `--version` | |

# Errors and exit codes (/reference/errors)

## Exit codes [#exit-codes]

The CLI ends every command with one of these:

| Exit | Meaning | What to do |
|---|---|---|
| 0 | Done | |
| 1 | Failed | Read the message. The provider may have failed; nothing was charged. |
| 2 | Usage | Fix the command. A parameter in the wrong part says where it goes. |
| 3 | Needs confirmation | Show the user the preview and price. Only if they agree, run the command it prints (with `--confirm`). |
| 4 | Refused by a rule | Tell the user which rule. If they want it, `supe approve <tool> --reason "…"`. |
| 5 | Wallet empty | Give the user the link to add credits. |
| 6 | Long job still running | `supe job <job_id>` later |
| 7 | Not signed in | `supe login --email …` |

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

## HTTP errors [#http-errors]

Every error is `{"error": {"code", "message", "details"}}`:

```json
{"error": {"code": "price_above_max", "message": "openalex#works_search costs 1 credit, above max_price 0 credits."}}
```

| Status | Code | Meaning |
|---|---|---|
| 400 | `invalid_request`, `invalid_input` | Fix the call. `invalid_input` says which parameter and where it goes. |
| 401 | `unauthorized` | Missing or unknown key |
| 402 | `insufficient_balance` | The wallet can't cover it |
| 402 | `limit_reached` | A budget is used up |
| 402 | `run_budget_exceeded` | This run's budget is used up |
| 402 | `price_above_max` | The tool costs more than `max_price` |
| 403 | `tool_disabled`, `tool_not_allowed` | The tool is off, or this agent may not use it |
| 403 | `workspace_frozen` | All spending is paused |
| 403 | `tool_not_compliant` | The tool can't be used from this workspace |
| 404 | `not_found` | No such tool, tag, provider, run or job |
| 409 | `needs_confirmation` | Show `details.will_do` and `details.price`; resend with `confirmation` if they agree |
| 409 | `confirmation_changed`, `confirmation_invalid` | The input changed or the confirmation is stale. Ask again. |
| 409 | `awaiting_signature` | Waiting for the user's passkey. Send again. |
| 409 | `idempotency_in_progress` | The first request with this key is still running |
| 422 | `idempotency_mismatch` | Same `Idempotency-Key`, different body |
| 502 | `provider_error`, `fetch_failed` | The provider failed, or a file link couldn't be reached |
| 503 | `tool_unavailable` | The tool isn't available right now |
| 504 | `provider_timeout`, `job_expired` | The provider took too long, or a job's result expired |

The CLI maps these to exit codes: the 402 and 403 refusals are exit 4 (exit 5 for `insufficient_balance`), `needs_confirmation` is exit 3, and `unauthorized` is exit 7.

# HTTP API (/reference/http-api)

Base URL `https://service.oex.sh/v1`. Send `Authorization: Bearer <key>` on every request. The machine-readable contract is [`/v1/openapi.json`](https://service.oex.sh/v1/openapi.json). Amounts are in credits (1,000 credits are $1).

## Endpoints [#endpoints]

| Endpoint | What it does |
|---|---|
| `GET /v1/tags` | Every tag, what it means, and how many tools you can use carry it |
| `GET /v1/tools?query=&tag=&provider=&max_price=&limit=` | Tools, best first, with price and tags. 10 for a search; `more` counts the rest. |
| `GET /v1/tools/{id}` | One tool: method, path, parameters by part (`input`), price, docs, and up to 5 alternatives. Encode `#` as `%23`. |
| `POST /v1/run` | Run a tool |
| `GET /v1/jobs/{id}?wait=` | Collect a long job |
| `POST /v1/runs` | Open a run: `{"goal", "budget"}` |
| `GET /v1/runs`, `GET /v1/runs/{id}` | Runs and their receipts |
| `POST /v1/files` | `{"name"}` for a one-time `upload_url`, or `{"url"}` to store a copy of a link |
| `GET /v1/files?name=` | Files in the workspace |
| `GET /v1/recipes?query=`, `GET /v1/recipes/{id}?tier=`, `POST /v1/recipes` | Find, read and save recipes |
| `GET /v1/rentals`, `POST /v1/rentals/{id}/release` | Rented numbers and inboxes |
| `GET /v1/wallet` | `balance`, `held`, `available` |
| `GET /v1/me`, `PATCH /v1/me` | The workspace and this agent; `{"name"}` renames the agent |
| `POST /v1/approvals` | Ask a person: `{"kind": "tool_access" or "budget", "tool_id", "reason", "amount"}` |

## POST /v1/run [#post-v1run]

```json
{
  "tool": "serper#search",
  "input": { "body": { "q": "lighthouses", "num": 5 } },
  "max_price": 10,
  "run_id": "run_…",
  "budget": 500,
  "goal": "find lighthouse photos",
  "confirmation": "act_…"
}
```

| Field | |
|---|---|
| `tool` | Required. An exact tool id. |
| `input` | `{path, query, body}`, each with the tool's own parameter names in the part `GET /v1/tools/{id}` lists. Leave out parts the tool doesn't take. |
| `max_price` | Refuse if the call costs more (`402 price_above_max`) |
| `run_id` | Bill an open run. Without it, a run opens with `budget` (default 1,000) and `goal`. |
| `confirmation` | Go ahead with a call that answered `409 needs_confirmation` |

### Answers [#answers]

- **`200`**: `{status: "succeeded", tool_id, tags, data, results, cost, unit, run_id, test, latency_ms, receipt_url}`. `data` is the provider's own response.
- **`202`**: `{status: "running", job_id, run_id, elapsed_s, check_again_in_s, poll}` for a job still going after about 45 seconds. Collect it with `GET /v1/jobs/{id}?wait=20`.
- **4xx/5xx**: `{"error": {"code", "message", "details"}}`. Nothing is charged. See [Errors](/reference/errors#http-errors).

A test key (`oex_test_…`) gets an empty answer of the tool's kind and `test: true`. Nothing is called or charged.

### Idempotency-Key [#idempotency-key]

Send any unique value as an `Idempotency-Key` header. A retry with the same key and body returns the first answer, with `Idempotent-Replayed: true`, for 24 hours. The same key with a different body is `422 idempotency_mismatch`; one still in flight is `409 idempotency_in_progress`.

# MCP tools (/reference/mcp-tools)

The server also sends the agent instructions: the find, inspect, run loop; prices in credits; asking before anything that can't be undone; and collecting long jobs. You don't need to add your own.

## Tools [#tools]

| Tool | What it does | Changes anything |
|---|---|---|
| `find_tool` | Tools for a job in plain words, with price and tags. Filter by `tag`, `provider`, `max_price`. | No |
| `inspect_tool` | One tool's parameters by part, price, docs and alternatives | No |
| `execute_tool` | Run a tool with `tool_id` and `input` (`{path, query, body}`). Takes `run_id`, or `budget` and `goal` to open a run, and `confirmation`. | Yes, billed |
| `start_run` | Open a run with a `budget` and `goal`; returns its `run_id` | Yes |
| `get_run` | A run's receipt | No |
| `get_job` | Collect a long job by `job_id` | No |
| `add_file` | Make a link for a file: a one-time upload page, or a copy of a `url` | Yes |
| `list_files` | Files in the workspace | No |
| `wallet_balance` | Balance and what's held, in credits | No |
| `list_rentals` | Rented numbers and inboxes | No |
| `release_rental` | Stop renewing a rental. Can't be undone. | Yes |
| `request_approval` | Ask a person for a tool (`tool_access`) or more `budget` | Yes |
| `find_recipe` | Search recipes | No |
| `get_recipe` | A recipe's inputs and steps | No |
| `save_recipe` | Copy a Cookbook recipe, or save a new one | Yes |

## Prompt [#prompt]

`recipe` takes a recipe's id or name and starts the agent on it.

## Refusals [#refusals]

A refused call isn't an error. It comes back with a `reason` (budget, balance, limit, disabled, frozen) and a `next` step, and the agent tells you. `execute_tool` returns `status: "needs_confirmation"` for anything that needs your yes. See [Confirmations](/use/confirmations).

# Confirmations (/use/confirmations)

Some tools do something you can't take back: send an email or SMS, place a call, rent a number. These never run on the first call. supe answers with a preview of exactly what would happen and what it costs, and waits.

You can also make supe ask first for anything over an amount you choose, under [Limits](/controls/limits).

## What the agent does [#what-the-agent-does]

With the CLI, the call exits with code **3** and prints the preview and the command to go ahead:

1. The agent shows you the preview and the price.
2. Only if you agree, it runs the command supe gave it, which is the same call with `--confirm <id>`.
3. If the preview includes an approve link, you approve there with your passkey (Face ID or Touch ID). The confirm command waits for it.

The confirmation is tied to that exact input. If the agent changes anything, supe refuses it (`confirmation_changed`) and asks again.

## Face ID [#face-id]

Under **Controls → Approve with Face ID** you choose when your passkey is needed:

| Setting | Face ID is needed for |
|---|---|
| Off | Nothing. A yes in chat is enough. |
| Permanent | Anything that can't be undone. |
| Everything I'm asked | Every confirmation, including your ask-me-over amount. |

With Face ID on, a yes in chat isn't enough: someone with your passkey has to approve. Changing this setting, adding a passkey or removing one also needs your passkey.

## Over HTTP and MCP [#over-http-and-mcp]

- HTTP: `POST /v1/run` returns `409 needs_confirmation`. Show `error.details.will_do` and `error.details.price` to a person; if they agree, send the same request with `"confirmation": error.details.confirmation`. If it needs a passkey, the retry waits for it, or returns `409 awaiting_signature` to try again.
- MCP: `execute_tool` returns `status: "needs_confirmation"` with `will_do` and the price. The agent asks you, then calls again with `confirmation`.

# Files (/use/files)

Providers read photos, recordings and documents from public links. supe makes those links for you.

## Pass a local file [#pass-a-local-file]

Any parameter named `*_url`, `*_urls`, `images` or `files` takes a local path. supe uploads the file first (up to 20 MB) and sends the link:

```bash
supe fal#bria_background_remove --body image_url=./photo.png
```

`url` works too when the value looks like a path, like `./page.html`.

## Upload once, use many times [#upload-once-use-many-times]

```bash
supe upload ./photo.png          # prints the file's link
supe upload https://example.com/report.pdf   # stores a copy of a link that may expire
supe files                       # files in this workspace, with their links
supe files photo.png             # just that one
```

Anyone with a file's link can read it.

## Get a file from a person [#get-a-file-from-a-person]

When your user has the file and you don't:

```bash
supe upload --link contract.pdf
```

This prints a one-time page. Give the link to the person; they upload the file there. Then check for it with `supe files contract.pdf`.

## Over HTTP and MCP [#over-http-and-mcp]

- HTTP: `POST /v1/files` with `{"name"}` returns a one-time `upload_url` to `PUT` the file to; with `{"url"}` it stores a copy of that link. `GET /v1/files?name=` lists them.
- MCP: `add_file` and `list_files`.

# Find and run a tool (/use/find-and-run)

## Find [#find]

Describe the job in plain words:

```bash
supe find "exchange rates"
```

```text
  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:

```bash
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 [#inspect]

```bash
supe inspect frankfurter#rate
```

```text
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 [#run]

Give each parameter with the flag for its part:

```bash
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:

```text
supe: frankfurter#rate: 'from' goes in `path`, not `query`.
```

For bigger input, pass the whole thing as JSON:

```bash
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-answer]

The CLI prints the provider's response, then the tool, the cost and the receipt link. Add `--full` for everything as JSON:

```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:

```bash
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 [#price-caps]

`--max-price` refuses a call that costs more, before it runs:

```bash
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 [#local-files]

A tool that takes a link also takes a local file. supe uploads it first (up to 20 MB):

```bash
supe fal#bria_background_remove --body image_url=./photo.png
```

This works for parameters named `*_url`, `*_urls`, `images` and `files`. See [Files](/use/files).

# Long jobs (/use/long-jobs)

Some tools take minutes: making a video, deep research, a phone call. Their price is held while they run and charged only if they succeed.

## With the CLI [#with-the-cli]

`supe run` waits for a long job and prints the answer when it's done. To get on with other work instead:

```bash
supe run <tool> ... --no-wait      # prints the job id and exits
supe job <job_id>                  # collects it, waiting if it's still going
```

If a job is still running when the CLI stops waiting, it exits with code **6** and the job id. Run `supe job <job_id>` later.

## Over HTTP [#over-http]

`POST /v1/run` returns `202` with `status: "running"`, a `job_id` and `check_again_in_s` when a job is still going after about 45 seconds. Collect it:

```bash
curl -s "https://service.oex.sh/v1/jobs/<job_id>?wait=20" -H "Authorization: Bearer $SUPE_API_KEY"
```

`wait=20` holds the request up to 20 seconds. You get `200` with the answer when it's done, or `202` while it's running.

## Over MCP [#over-mcp]

`execute_tool` returns `status: "running"`. The agent tells you it's under way, then calls `get_job` with the `job_id` after `check_again_in_s`.

# Recipes (/use/recipes)

A recipe is a job of several tool calls, written down: its inputs and its steps, each step a tool id and its input. "Product photo to video ad" or "research a company and email its CEO" are recipes.

## Find one [#find-one]

```bash
supe recipes "product photo to video ad"   # search the Cookbook and your own
supe recipes                               # just your own
supe recipe <id>                           # its inputs and steps
```

Some recipes have tiers, like a budget and a premium version: `supe recipe <id> --tier budget`.

## Follow one [#follow-one]

Each step is an ordinary `supe run`. Fill `{{inputs.name}}` with the job's inputs and `{{steps.<id>.<field>}}` with an earlier step's answer. Open one [run](/use/runs-and-budgets) for the whole recipe so it has one budget and one receipt.

Any text a step needs, like a summary, an email or a script, the agent writes itself. Recipes have no step that writes text.

Community recipes in the Cookbook aren't checked by supe. Read the steps before running one.

## Keep or write one [#keep-or-write-one]

```bash
supe recipe save <id>          # copy a Cookbook recipe into your workspace
supe recipe save -f recipe.json   # write your own: name, description, inputs, steps
```

Saved recipes show up on the dashboard under Recipes.

Over HTTP: `GET /v1/recipes?query=`, `GET /v1/recipes/{id}`, `POST /v1/recipes`. Over MCP: `find_recipe`, `get_recipe`, `save_recipe`, and the `recipe` prompt.

# Runs and budgets (/use/runs-and-budgets)

A run is a budget ceiling plus one receipt. Every paid call belongs to one. If you don't open a run, each call gets its own with a default budget of 1,000 credits ($1).

For a job of several calls, open one run and bill every call to it. Then a loop can't spend more than you meant, and you see the whole job on one receipt.

## Open a run [#open-a-run]

```bash
export SUPE_RUN=$(supe budget 2000 --goal "enrich 50 leads" --json | jq -r .run_id)
```

`supe budget 2000` opens a run that may spend at most 2,000 credits ($2). `--goal` is the line you'll see on the receipt. With `SUPE_RUN` set, every call bills to that run. Use `--run <id>` to pick a run for one call.

When the run's budget is used up, the next call is refused with `run_budget_exceeded` (exit 4). Nothing is charged for it.

## The receipt [#the-receipt]

```bash
supe receipt $SUPE_RUN
```

```text
docs  ·  1 credit spent of 2,000 credits
  openalex#works_search                        1 credit  ok
https://app.oex.sh/activity/run_a45b043e2757
```

`supe runs` lists recent runs. On the dashboard, Activity shows every run with its steps.

## One call, one cap [#one-call-one-cap]

```bash
supe run serper#search --body q=lighthouses --budget 50 --goal "one search"
```

`--budget` caps the new run this call opens. `--max-price` refuses the call outright if the tool costs more than that.

## Over HTTP and MCP [#over-http-and-mcp]

- HTTP: `POST /v1/runs` with `{"goal", "budget"}`, then pass `run_id` in each `POST /v1/run`. Or give `budget` and `goal` on the first `POST /v1/run` and reuse the `run_id` it returns. `GET /v1/runs/{id}` is the receipt.
- MCP: `start_run`, or `budget` and `goal` on the first `execute_tool`; then `run_id` on the rest. `get_run` is the receipt.

Run budgets sit inside your workspace [limits](/controls/limits): a call has to fit both.