Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Quickstart

You need an API address and a key. For a quick look without an account, the landing page has a terminal that runs the real CLI against a throwaway demo account.

with the CLI

export ORSEL_URL=https://your-deployment export ORSEL_KEY=orsel_xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx orsel find "read a blog post by id" --pages none orsel act jsonplaceholder.typicode.com get_post --input '{"id": 3}' orsel verify
find prints actions with their risk class, what your policy would do, and why each ranked. act prints the tier used, the typed result and whether its checks passed. verify recomputes the ledger chain.

with the TypeScript SDK

import { Orsel } from 'orsel'; const orsel = new Orsel(); // reads ORSEL_KEY, ORSEL_URL, ORSEL_PROJECT const found = await orsel.find('read a blog post by id', { pages: 'none' }); const top = found.topAction; if (top) { const run = await orsel.act({ domain: top.domain, actionId: top.actionId, input: { id: 3 } }, { wait: true }); console.log(run.ok ? run.output : run.errorCode); }

with REST

curl -s "$ORSEL_URL/v1/act" \ -H "authorization: Bearer $ORSEL_KEY" -H "x-project-id: $ORSEL_PROJECT" -H "content-type: application/json" \ -d '{"domain":"jsonplaceholder.typicode.com","actionId":"get_post","input":{"id":3}}'

a site with no actions yet

act runs only sites that have a recipe. For any public site you can make read actions from its own pages:
orsel explore https://www.python.org/about/ orsel act python.org search_site --set query=django
explore turns a site into actions you can call (from code: orsel.site('python.org'); see use a website as an API). It asks robots.txt first, then fetches up to 28 pages as orsel-bot (one every half second unless the site names a crawl delay, several in flight at once, and it stops after a minute), using the links on the page, the home page and the sitemap as the map. Each action is one route of the site:
  • read_<section>_page is /blog/{slug}: it returns the title, description, canonical url, image, language, the headings, the content as Markdown in page order (headings, lists, tables and code stay where they are) and the links (each once, at most 60) of one page, whichever of those every sampled page has.
  • list_<section> is /blog: it returns the titles and links of the section's index, plus slugs (feed one to the read action next to it) and dates when each item has one. When the index page shows no list (images, or drawn by JavaScript) the section is listed from the site's sitemap instead (up to 300 pages).
  • read_<page> is a named page from the navigation (/about, /pricing).
  • search_site is /search?q={query}: from a search form that works with a plain link, from the search the site advertises (OpenSearch), or from a JSON endpoint: WordPress, Shopify, Discourse and Mastodon have one, and so does any route the site's docs or JavaScript show with a q= or search=. A search drawn only by JavaScript that calls an endpoint nothing shows is not made, and the output says so.
  • sign_in, sign_up, contact and subscribe are the site's POST forms (POST /session). They are never submitted while exploring: each is checked against the form, and carries a risk class so it waits for approval (write for contact and subscribe, sensitive for sign in and sign up). A password is a secret, never an input, so it cannot end up in a run record; a token field (csrf) is read from the form page in the same run. Any other POST form becomes submit_<path>, with a risk class from what it does: irreversible for deleting or closing (it always needs a person), sensitive for accounts, profiles, settings and keys, write otherwise. Create, update and delete come from the site's API, not its pages, so explore looks for it in four places: an OpenAPI or Swagger 2 document (every operation becomes an action with the importer's risk class: write for create and update, irreversible for delete); the routes a documentation page lists (GET /posts, DELETE /posts/1), which are checked against a real answer when they are reads; the routes the site's own JavaScript calls (fetch('/api/items', { method: 'POST' })), when nothing better was found; and the routes of the platform the site runs (WordPress, Shopify's storefront and cart, Discourse, Mastodon). Reads are checked against a real answer and run freely. Everything that changes something is described from the route and never run while exploring, takes its body as input.body, names the secrets it needs (a token, an application password), and waits for approval. When the site publishes its own API, explore uses that instead of guessing from pages: an OpenAPI 3 document (/openapi.json, or one the page links as service-desc) goes through the same importer as orsel import, so each operation becomes an action with the importer's risk class and none is run; WordPress sites (the page links https://api.w.org/) get wp_list_posts and wp_get_post, which run against the real answers. A form behind a captcha, one that takes card or bank details, one that uploads a file, and one that posts to another site are not made, and the output says which and why. Hosted runs have no secret store yet, so sign in and sign up cannot run there; contact and subscribe can, after approval. A sign in counts only when the run leaves the form's page, since a failed one shows the same form again.
The result prints each route with what it takes and returns, and a command with a real example input you can paste. --json gives the same as data: kind, route, inputs, outputs, example. Every kept action was run against the fetched pages, on the sample and on other inputs, before it was kept; what was not made comes with the reason. They are candidates that only your organization can run until the daily checks verify them. It refuses sites with a verified owner, who publish their own actions, and it needs an act:write key. Start from the home page to get the most. It cannot make actions for pages that are drawn by JavaScript, that need a login, or whose forms post data; those need a recording (orsel import) or your own browser.

shorter results

A page is a lot of text. act can cut the result down, and says what it cut in _shaped, so a short result never looks complete when it is not:
orsel act figma.com read_home --fields title,headings --limit 10 --max-chars 2000
--fields a,b.c keeps only those fields, --limit N keeps the first N items of every list, --max-chars N the first N characters of every text, --unique drops repeated values. In code: blog.read_blog_page({ slug }, { shape: { fields: ['title'], limit: 5 } }). Over MCP, orsel_act shortens by default (40 items, 6000 characters) and takes fields, limit and maxChars. www.figma.com, figma.com and https://Figma.com/ are the same site everywhere.

writes

A write is refused unless your policy allows it, and needs an Idempotency-Key. Run orsel policy approve-writes (an admin key) to make writes and sensitive actions stop at awaiting_approval (CLI exit code 6) instead; deny-writes puts the default back. Irreversible and financial actions always need a person. A person approves it with orsel approve <id> or in the dashboard.

for an agent

Run orsel init in a project. It writes the MCP config, the skill, the rules for Cursor and Codex, and the Claude Code hook, merging into what exists. Add --dry-run to see the files first.