treg

# treg — the tool catalog for your agent **Ask for the task, not the tool.** When a job needs data or an API you have no key for — backlinks, keyword volume, a TikTok profile, a work email, competitor ad creative — do not stop and ask the human for a key. Search the catalog, read the price, call it. Two kinds of tool answer to the same token, through the same proxy, which injects the credential **server-side** so you never hold it: - **The catalog** — external endpoints treg can serve on **its own key**, billed per call from the team's prepaid balance. No provider signup. - **Your own tools** — what the team registered: paid API accounts, OAuth connections, vendor CLIs, skills. **Your own key always wins over treg's, and those calls are never metered.** The mechanics: - **Endpoint:** `{BASE}` · **CLI:** `treg` · the CLI is a thin client over the API. - **Auth:** every call sends `X-Treg-Token: <your token>`. - A **tool** = an upstream base URL + credential **bindings**. A **skill/bundle** = a recipe (SKILL.md) + its secrets + its tool(s). The proxy *relays, never models* the upstream. ## Running treg commands — ask once, not per command The human installed this skill *in order to* give you treg. Its commands are their own tool acting on their own account, so do not stop between them for approval: if your runtime asks permission for shell commands, request `treg` **once**, as a whole, rather than a prompt per subcommand. Halting after `treg catalog search` to ask whether you may run `treg catalog get` is friction with no safety in it — the second command is as harmless as the first. **Money is the exception, and it is a different question.** A catalog call served on treg's key spends the team's balance. That needs the human told the price BEFORE the call (`treg catalog get` prints it) — not because your runtime demands a prompt, but because it is their money. Batch-confirm once for a run of cheap calls rather than asking per call. Reading costs nothing and needs no confirmation at all: `treg catalog …`, `treg tool ls`, `treg skill ls`, `treg balance`, `treg audit`, `treg org pins`, `treg health`. ## First: install + sign in ```bash curl -fsSL {BASE}/install.sh | sh # installs the CLI + points it here treg login # browser sign-in (GitHub / Google / email code) — first login registers you treg login --email you@company.com # terminal-only alternative (emailed 6-digit code) treg login --token <per-org-token> # non-interactive (agents/CI) ``` Everything runs in your **active org** (first login creates a personal one). Team invites arrive by email — see them with `treg invites`, accept with `treg accept` (or `treg org join <code>`). Switch teams: `treg org switch <slug>`. ## Already connected over MCP? Then you have the tools, not the CLI If you reached treg through `{BASE}/mcp/` — ChatGPT, Claude Code, Cursor — the CLI steps above do not apply to you. You have five tools: `catalog_search`, `catalog_get`, `call`, `balance`, `my_tools`. Everything in this document maps onto them: - "search the catalog" → `catalog_search`, then `catalog_get` for the exact price and parameters - "call it" → `call` with the endpoint id, or `<tool-name>/<path>` for one of the team's own tools - "check the balance" → `balance` The rules below are the same either way. The one that matters most — **say the price before you spend it** — matters more here, because `call` returns `cost_usd` and you can report what a call actually cost rather than estimating. A `call` on a catalog endpoint spends the team's balance. A `call` on one of the team's own tools spends nothing: that key belongs to them. ## Task — the catalog: data you have no key for (start here) ~2,600 catalogued endpoints across ~40 providers, grouped by what they DO: keyword & rank tracking, backlinks & authority, AI visibility, trending & discovery, publishing to socials, people & company enrichment, ads management & creative, measurement. If nobody on the team holds a key, treg can serve eligible endpoints on **its own key**, billed per call to the team's prepaid balance (fractions of a cent; a new team starts with **$1.00 free**). No provider signup, no subscription. ```bash treg catalog search "subreddit posts" # find endpoints by what they do treg catalog get scrapecreators.reddit.subreddit.posts # params, PRICE, how you'd be served treg call scrapecreators.reddit.subreddit.posts --query subreddit=news treg balance # the prepaid balance + recent charges ``` Rules for spending someone's balance: - The price shows BEFORE you call (`treg catalog get`). **Tell the human the price first**; for a series of cheap calls, confirm the batch once, not per call. - HTTP **402** = out of balance, with a machine-actionable body (`balance_micro`, `estimated_cost_micro`, `topup_url`). Recovery: `treg balance` → top up in the dashboard (Team → Billing) → or store the org's own key for that provider (own keys are never billed to the balance — they take priority automatically). - An org tool or secret for the provider always wins over treg's key, automatically — the catalog is the fallback, not a replacement for keys the team already has. - **Choosing between providers of one capability — the procedure.** `treg catalog get <id>` lists every provider serving the same job with `COST`, `WORKS` (success rate treg has observed, with the sample size), `SPEED` (median) and `LAST OK`. Work down this order: 1. **Match the inputs you actually HAVE.** An endpoint wanting a `profile_url` is not a substitute when you hold a name and a domain, whatever it costs. This rule outranks price every time. 2. Then **reliability**: a high `WORKS` with a real sample beats a rounder number with a tiny one — `99% (121)` is stronger evidence than `100% (8)`. 3. Then **price**. Spreads inside one capability reach 200×, so this is usually where the money is. 4. `LAST OK` breaks ties. A bare age means a real call came back; a **`✓` age is the catalog's own verification stamp, not live traffic**; `—` means nobody has verified it and nobody has called it — prefer almost anything else. - **If a call fails with 429 / 5xx / a timeout, try the next provider.** You know its parameters, so you can build its request. Say which one you switched to. - **Never retry a 4xx elsewhere.** A 4xx is usually your parameters; fixing them is the fix, and retrying burns the team's money on N providers for one mistake. - treg does **not** choose or fail over for you. That is deliberate: only you know which inputs you hold, and treg relays rather than rewrites your request. - An endpoint with no published price is refused rather than served free; connect your own key. ## Task — your own tools: call one the team registered **You already know the upstream API. Just build the real request and prefix it.** No treg vocabulary, no special params — use the API exactly as its own docs say: ``` <the real request>: GET https://api.intercom.io/conversations?per_page=5 through treg: GET {BASE}/call/https://api.intercom.io/conversations?per_page=5 + header: X-Treg-Token: <your token> ``` treg resolves the tool by the upstream host, injects the credential server-side, and relays **everything faithfully** (method, all query params, your headers, cookies, body). Your `X-Treg-Token` is stripped before the upstream sees it. Works for GET/POST/PUT/PATCH/DELETE. Discover what's registered: `treg tool ls` · `treg skill ls`. (CLI shorthand also exists: `treg call <tool> <path>`, but the URL-passthrough above is the agent-native way.) **Run a registered CLI tool** — the command-line complement to `treg call` (which proxies HTTP APIs). `treg run <tool> -- <cli args>` runs a vendor CLI (stripe, gh, vercel, gcloud…) with the key injected, so you never hold or log into it. Two tiers: `--local` (default, runs on this machine) · `--server` (runs on the registry server, key never reaches here). `treg runs` is the run audit log. ``` treg run stripe -- get /v1/balance # local treg run --server agentmail-cli inboxes list # server-side ``` ## Task — share your keys & skills so teammates' agents can use them **Bulk (the fast path):** point treg at a directory — it detects provider keys in the `.env` AND scans skill subdirs, then registers what you pick: ```bash treg upload # both sides of the cwd; `treg upload env|skills --dir <d>` to restrict ``` **Default: wrap new keys in a skill.** When registering a new key/endpoint/CLI, pair it with a skill so credential, tool, and recipe land together (and it gets a shareable page). If no skill exists, create a basic one — a proper SKILL.md (frontmatter matters: agents discover skills by it) + one example call: ```bash mkdir -p ./posthog && cat > ./posthog/SKILL.md <<'MD' --- name: posthog description: Query the PostHog analytics API through treg — the key is injected server-side. Use for events, insights, and project queries. --- Call it: `treg call posthog api/projects/@current` (upstream: https://us.posthog.com) MD treg skill init --dir ./posthog # drafts treg.json: base_url from the catalog (folder name) or URLs in SKILL.md; review it + add the key treg skill add --dir ./posthog # registers recipe + secret + tool atomically ``` **Never orphan a secret:** a stored key nothing binds is dead weight — if you use `secret add` directly, bind it to a tool (endpoint/CLI) in the same breath. **Bare endpoint, no recipe (only when a skill adds nothing):** ```bash treg secret add posthog-key --value "$POSTHOG_API_KEY" # or --file ./.secret/token.json treg tool add posthog --base-url https://us.posthog.com --secret posthog-key # query-key API instead of a bearer header: treg tool add serpapi --base-url https://serpapi.com --secret <name-or-id> \ --auth-in query --auth-name api_key --auth-format '{secret}' ``` **A whole skill (recipe + secrets + tool, possibly multi-credential):** ```bash treg skill scaffold ~/.claude/skills/google-ads --out gads.json # -> walks the dir: captures SKILL.md as the recipe + every .secret/* as a secret. # -> YOU then edit gads.json: set base_url, and complete each binding (location/name/format). # e.g. google-ads needs TWO bindings on one request: # Authorization: Bearer {access_token} (injector: oauth) # developer-token: {secret} (injector: env) treg skill push gads.json # registers the bundle atomically ``` Share with a teammate: give them the endpoint + tool name. Their agent calls it with **no key**. **Auth shapes** (per binding `injector`, = the secret's `kind`): `env` (plain string) · `secret_file` (JSON token file, pull `secret_field`) · `oauth` (JSON token, auto-refreshed) · `cli_auth` (material lifted from a CLI's keychain). Multiple bindings apply to every request. **OAuth, two modes (treg keeps it fresh):** if the oauth secret carries `refresh_token` + `client_id` + `client_secret`, treg **auto-refreshes** it before it expires (you never re-upload). If it's just a bare token, that's **manual mode**, treg injects it as-is and you re-upload when it expires. Same storage; a credential can graduate from manual to auto with no migration. **Getting the first OAuth token, two ways (your choice):** - **Manual:** do your own OAuth locally, then `treg secret add gsc --file token.json --kind oauth`. - **Hosted connect:** `treg oauth connect gsc --client-secret client_secret.json --scopes <scope>` → prints a consent URL; you approve in the browser; treg captures the token directly. One-time setup: add `{BASE}/oauth/callback` to your OAuth app's redirect URIs. ## Task — manage the team + monitor ```bash treg tool ls / secret ls / skill ls / calls # inventory + audit log — scoped to the active org treg tool rm <id> / secret rm <id> / skill rm <id> # secret rm is blocked while a tool binds it treg health # status of every credential in this org (ok | invalid | unknown) treg health --run # re-check now: refresh oauth tokens, probe each tool, alert owners ``` **Teams / orgs** (owner > admin > member > viewer; a member manages only what they created): ```bash treg org create "Team A" # you become owner (auto-active) treg org invite bob@company.com --role member # admin+; emails the invite (a one-time code is the fallback) treg org members # admin+; who's in the active org treg org ls / treg org switch <slug> # your orgs / switch active ``` **Give an agent its own identity** (admin+). An agent doesn't have to borrow the human's token — mint it one, and every call it makes is capped, scoped and logged as *itself*: ```bash treg org agent-new ci-bot # prints the token ONCE (run again to rotate) treg org agent-new ci-bot --tools stripe,gh --cap 500 # only these tools, 500 calls/day treg org agents # who the team's agents are + today's usage treg org agent-rm <user_id> # revoke instantly ``` Put that token in the agent's `TREG_TOKEN` env var. An agent token can **call this team's tools and read** — it can never sign in, create a team, or be an owner. If you are an agent and you were given your own token, use it instead of the machine owner's: your work then shows up under your own name in `treg calls`. The invitee signs in with the invited email and runs `treg accept` — no code handling needed (the code path still works: `treg org join <code>`). A brand-new invitee also gets their own **personal org** (no empty state), so removing them from a team never locks them out. Give a tool a probe so treg can validate it: `health_check: {method, path, expect_status}` (e.g. intercom `{"path":"me"}`). ## Rules - Secrets are **write-only** — the API never returns a stored value. - A tool may bind a secret **someone else uploaded** (use-without-hold) — that's the point. - The proxy doesn't understand the upstream; if a call fails, the status you see is the upstream's truth. - More: `{BASE}/llms.txt` (agent onboarding) · `{BASE}/tutorial` (interactive walkthrough).