openbash

npx add-mcp 'https://openbash.ai/api/mcp'

openbash

Bash programs over data. One command line in, one answer out.

The programs below are commands on a path, not endpoints. There is ONE exec call, and a pipeline of several programs is a single request to it. They compose with pipes, redirection and the ordinary shell tools, so two of them can be joined without a schema for the join.

Which programs exist is decided per ACCOUNT, not per call. Once one is enabled every session that account opens has it, and "help" lists exactly those: so "help" is the authoritative answer to "what can I run", not this page.

Setting yourself up

If you are an agent reading this because somebody pasted a link at you, this is the step they meant:

curl -fsSL https://openbash.ai/install.sh | sh -s -- --key sk_ob_...

It writes https://openbash.ai/skill.md — how to use this shell, as instructions — into every agent directory on the machine, checks the key by running one free command, and registers the MCP server below with that key as a header. No browser, and nothing to install: there is no CLI, because the API is one HTTP call and curl is already its client.

Without a key it still installs the skill and tells you where to get one. With no key at all, the MCP door below runs an ordinary OAuth consent screen.

Three doors, one shell

HTTP   POST https://openbash.ai/api/v1/exec   {"command": "..."}
MCP    ssh -p 38449 <your-key>@ssh.openbash.ai '<command>'/api/mcp            one bash tool (https://openbash.ai/api/mcp/sandbox adds typed file, library and figure tools, for a hosted harness)
SSH    ssh -p 38449 <your-key>@ssh.openbash.ai '<command>'

They are three ways into the same account-scoped shell, not three services. Whichever you use, the same programs are on the path and the same key decides which ones.

Output contract

• JSON on stdout, one object per line, so jq composes across programs.
• Every record carries source (what it was read from) and as_of (when that source was current). as_of is NOT the time you ran the command.
• A derived figure is marked "derived": true and carries its inputs. A figure you cannot check is a figure you should not use.
• Absence is a value. A program that finds nothing says so and exits 3; it does not return an empty object that reads as zero.

Exit codes

0   results
1   usage error. The flag or argument was wrong
2   not entitled. The program exists but this key does not have it
3   no results found. The query was valid and matched nothing
4   upstream data failure. The source could not be read

2 and 3 are different answers and it matters: 3 means there is nothing there, 2 means you were not allowed to look.

Reading the errors

Errors are the documentation. An unsupported flag names the flags that are supported; an unknown command names the near misses. Try something, read the failure, adapt. That path is designed to work.

Discovery

GET https://openbash.ai/api/v1/programs      the catalog, including programs this key lacks
GET https://openbash.ai/api/v1/programs/{slug}/surface/{read}  a program's browsable page as data, for the programs whose catalog entry carries a surface
GET https://openbash.ai/api/openapi.json     the OpenAPI spec for every endpoint
<program> --help                          the definition of one program

Keeping up

New programs are new capabilities on this shell, and there is no need to re-read the catalog and diff it to find them.

GET https://openbash.ai/api/v1/changelog     what was added and when, newest first, as JSON
GET https://openbash.ai/feed.xml             the same list as Atom
GET https://openbash.ai/sitemap.xml          every page, with the date it last changed

A program's date is when it first appeared, not when the catalog last synced, so an entry that is new to you is genuinely new.

Programs

• mail: Write a draft into this account's connected Gmail or Outlook. Nothing is sent.
• biotech: Targeted biotech studies as JSON: clinical trials, drug labels and approvals, company filings, literature.
• aero: Every flight movement for an airport-day, plus per-terminal and per-hour rollups, as JSON.
• trade: US customs bills of lading: a company's counterparties, its shipments, and the firms already importing what you make.
• outreach: Companies matching a description, the people at them, and their addresses — published, derived, or verified against a mail server.
• social: One surface over X, LinkedIn, Instagram and YouTube: profiles, posts, comments, reactions and search.
• realestate-us: Rental listings merged across sources, plus the HUD tables that decide what a subsidised rent may be.
• realestate-in: Rental listings around a place in an Indian city, merged across backends and deduplicated.
• places: Find a place by describing it, get its id and coordinates, then fetch what it looks like.
• commerce: SEC filing text by ticker, 13F ownership, and the name-to-ticker lookup you need before either.
• ocr: Optical character recognition over a file on a drive or a url. The whole document, or each line with where it sits.
• vision: A vision model reads images from a drive or a url and answers in words: what is in it, what it says, whether two match.
• dbq: Read-only SQL against the account's connected database, with results as CSV on stdout.
• rank: Keyword position on Google, and who is above you.
• dns: Mail authentication, nameservers and registration.
• webaddress: Categories and subcategories in the shape of a classifieds front page, each holding the addresses worth knowing; ask any branch for its top ten, local to a place.
• registry: npm downloads, GitHub stars, forks and last push.
• series: The history a measuring program leaves behind, and which way it went.
• browser: Search the web, take originals, and drive a live browser session.
• pplx: Perplexity's index from the shell: ranked results for a question, and the passages of a page that bear on it.
• pdftext: A PDF's text as markdown, with a readability check that runs without extracting.
• doctext: Text of a doc, docx, ppt, pptx, rtf, odt, odp or epub as markdown.
• blueprint: A drawing written as SVG, rendered as a blueprint PNG and, if asked, filed under a URL the document embeds.
• edi: X12 as CSV: the 820 remittance and the 812 adjustment, with the reason code on every line.
• sheet: Spreadsheet cells as CSV, from xls, xlsx, xlsm, xlsb or ods.
• csv: Columns, counts, frequencies, sums, averages, filters and joins over CSV.
• jq: Filter and reshape JSON, the way every program here emits it.
• text: awk, sed, grep, rg, cut, tr, sort, uniq and the rest of the text coreutils, in the jail.
• files: cat, ls, find, cp, mv, mkdir, rm, stat, du, diff and the path helpers.
• archive: gzip, tar and zip, plus base64, checksums and hexdumps.

The shell

What the shell IS — the mounts on it, what this key can run, and the convention for citing sources in an answer — comes from the shell itself, not from this page. Run help through any door above, or request this page with your key and it will be included here.