mirror of
https://github.com/only-cli/oc.git
synced 2026-09-15 10:40:56 +02:00
only-cli
b71ca15eba
The feature landed with one sentence in the install paragraph, which named the three environment variables and nothing else. Anyone actually putting oc behind a corporate proxy had to read src/fetch.js to learn that an https target prefers HTTPS_PROXY and falls back to HTTP_PROXY while an http target uses HTTP_PROXY only, that a bare host:port is read as http://, that a socks URL is refused rather than ignored, or that NO_PROXY takes suffix, wildcard, host:port, and CIDR entries. All of that is now in a Proxies section, and every claim in it was checked against the merged code rather than written from the diff. Two limits are documented instead of left to be discovered. oc does not read ALL_PROXY, but the impers transport is libcurl underneath and reads it on its own, so a request oc treats as direct can still leave through a proxy; the same holds for the *.suffix, host:port, and CIDR forms of NO_PROXY, which libcurl does not parse. Verified live against a third party proxy by watching the egress IP: with only ALL_PROXY set, or with NO_PROXY=*.host naming the target, oc reported a direct fetch and the request went through the proxy anyway. And an IPv6 literal over HTTPS cannot work through a proxy today, because URL.hostname keeps the brackets, so net.isIP reads 0 and the SNI and certificate check both treat [2606:...] as a DNS name. The security properties a reader would otherwise have to assume are stated: the CONNECT tunnel still verifies the origin certificate (confirmed against expired, self-signed, and wrong-host endpoints through a real proxy), credentials in the proxy URL reach the proxy and nothing else including across redirects, private and internal targets stay refused, and a name that resolves publicly for oc and internally for the proxy is not something oc can detect, so the proxy is trusted for its own egress policy. The skill gets the short version, since an agent needs two things: that no flag or setup is required, and that a "proxy failed" or "blocked" line is a transport problem to report rather than a page to retry. llms.txt gets one fact next to the existing transport fact.
28 lines
4.3 KiB
Plaintext
28 lines
4.3 KiB
Plaintext
# only-cli
|
|
|
|
> only-cli (command: `oc`) turns websites into a command line interface for AI agents. Instead of fetching raw HTML (tens of thousands of tokens) or driving a headless browser with screenshots, an agent runs `npx @only-cli/oc open <url>` and gets a distilled text view of the page in a few hundred tokens, with numbered links and form fields it can act on. Works with Claude Code, Claude, ChatGPT, Codex, Gemini, Antigravity, and any agent that can run shell commands.
|
|
|
|
Key facts:
|
|
|
|
- Install: `npm install -g @only-cli/oc`, or zero-install with `npx @only-cli/oc`
|
|
- Commands: `oc open <url>` (compact view with numbered actions), `oc do <n>` (follow numbered link [n], or read [n] when it is text rather than a link), `oc find <query>` (where a string appears on the page already open), `oc read <n>` (one region in full), `oc next` (the next screenful), `oc raw [url]` (whole page as markdown, `--html` for cleaned HTML), `oc --help` for the full surface
|
|
- Default output budget is 500 tokens per page; `--budget <n>` adjusts it, and `find`, `read <n>`, or `next` collect what the budget cut without refetching the page
|
|
- The budget is a target rather than a hard cap: a page that would finish within about four times it is printed whole, because a second command costs the agent far more than the lines the cut would have saved
|
|
- The render leads with the page's main content and puts navigation, sidebar, and footer after it, so the budget is spent on what was asked for rather than on menus
|
|
- Benchmarked at roughly 45x fewer tokens than reading raw HTML, with per-task numbers at https://github.com/only-cli/benchmarks
|
|
- Works on any mostly-static website; tuned shortcuts ship for Hacker News, Reddit, GitHub, X, LinkedIn (public guest views), DuckDuckGo, Bing, Stack Overflow (via its Atom feeds and the Stack Exchange API), Yahoo Finance (quotes, history, markets), Wikipedia (articles, search, and other language editions), and the AWS, Google Cloud, and Microsoft Learn documentation sites (guides, CLI reference, and search)
|
|
- JSON APIs render like pages: an endpoint that answers with JSON becomes one numbered item per record, with the fields that differ between items kept and the ones every item shares stated once, so a search endpoint reads like a results page for a few hundred tokens
|
|
- A page that comes back with no readable text (JavaScript-only, a consent wall, a bot challenge) prints one line on stderr and exits 2, rather than reporting an empty render as a success. `--json` carries the same verdict as an `empty` field, so a caller can tell "nothing on this page" from "oc could not read this page" and fall back to a browser only when it is worth it
|
|
- A shortcut is `oc <site> <verb> [args]`: `oc hn top`, `oc reddit sub ClaudeAI`, `oc gh repo only-cli oc`, `oc ddg search claude code cli`, `oc learn doc azure/aks/what-is-aks`. Name the site by its short name, bare name, or domain (`oc hn`, `oc ycombinator`, `oc news.ycombinator.com`), the last argument takes every word after it so a query needs no quoting, and `oc sites` lists every site with its verbs. A shortcut resolves to a URL and then behaves exactly like `oc open <url>`
|
|
- X profiles and individual posts read without a login (about 390 and 260 tokens); X search, explore, and hashtag pages do not, and oc reports the block instead of guessing
|
|
- Outbound fetches honor `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` (and their lowercase forms), so oc works in a sandbox whose only route to the network is a proxy. An https target is tunneled with CONNECT and its certificate is still verified, credentials in the proxy URL reach the proxy and nothing else, and private or locally unresolvable targets stay refused. `ALL_PROXY` is not read
|
|
- Requests impersonate Chrome, so pages that block plain scripts often still work
|
|
- Agent skill included: `npx skills add https://github.com/only-cli/oc --skill web-browsing-cli` ([skills.sh](https://www.skills.sh/only-cli/oc/web-browsing-cli))
|
|
- No JavaScript rendering yet and no login sessions yet (both on the roadmap)
|
|
|
|
## Docs
|
|
|
|
- [README](https://github.com/only-cli/oc/blob/main/README.md): install, agent setup, commands, supported websites, benchmarks
|
|
- [CONTRIBUTING](https://github.com/only-cli/oc/blob/main/CONTRIBUTING.md): design principles, adding site definitions
|
|
- [Benchmarks](https://github.com/only-cli/benchmarks): token usage, speed, and success rate against other ways agents read the web
|