OpenDoc/cli
The OpenDoc command line v0.2.0

The manual, at your prompt.

odc — search and read offline docsets from the terminal

The OpenDoc search engine, without the window — it can even install the docs. A full-screen reader when you want to browse, plain text when you want to pipe, JSON when your editor asks. Same docsets, same index, no network.

$ curl -fsSL https://raw.githubusercontent.com/daidarzzz/opendoc-cli/master/install.sh | sh

Installs odc and opendoc-cli in ~/.local/bin. x86_64 and Apple Silicon.

One binary · GPL-3.0 · no account, no telemetry · All releases →

Fig. 1 — odc, live 1The query. rust: narrows it to one docset; the chip says so. 2Results as you type, with the matching letters lit and the real symbol kind. 3The reader: the exact section, typeset — headings, lists, highlighted code. 4This one is yours: click it, type, use ↑ ↓, Enter, / and Esc.
§ 1Synopsis

Run odc with nothing else and the reader opens. Pipe it, and it prints help instead.

Eight verbs. One index.

odc loads the same docsets folder and the same in-memory index as the OpenDoc app, so what you find in one, you find in the other. Every command understands the same query.

odc [tui] [--docset DOCSET] [QUERY]

The full-screen reader.

odc search QUERY… [--limit N] [--json]

A ranked table of matches — or JSON for scripts.

odc show QUERY… [--code | --raw | --copy | --json]

Prints one entry, typeset for the terminal. Alias: cat.

odc open QUERY… [--path]

Opens the page in your browser, or just prints its file path.

odc list [--json]

What is installed, with entry counts.

odc docsets catalog | install | update | uninstall ID

Browse DevDocs and Dash feeds and manage docsets — no desktop app needed.

odc update [--check]

Updates itself from GitHub Releases, checksums verified.

odc completions SHELL

Tab completion for bash, zsh, fish, PowerShell and elvish.

§ 2Queries

Short names work too: py, js, ts, rs, sh.

Say where to look, then what.

A query is fuzzy text with up to two optional prefixes. Leave them out and odc searches everything; add one and the haystack shrinks before the first letter is matched.

rust:fn:push docset kind text
docset
Id, name or alias. Optional.
kind
fn, struct, trait, macro… Optional.
text
Fuzzy. Several words match in any order.
Fig. 2 — Anatomy of a query DevDocs stores a category where Dash keeps the symbol type, so odc reads the real kind from the page itself: a method is fn, struct.Vec.html is a struct.
You typeYou get
Vec::pushFuzzy search across every installed docset.
rust:Vec::pushOnly the Rust docs.
py:json dumpsPython, by alias. Words can come in any order.
fn:mapFunctions and methods called something like map, in every language.
rust:fn:pushBoth at once.
std::vectorA double colon is never a prefix, so C++ stays C++.

Inside a project, odc notices Cargo.toml, package.json, go.mod or pyproject.toml and ranks that language first. --no-context turns it off.

§ 3Reading

Output longer than the screen goes through less -R, or your $PAGER.

The section you asked for, not the whole page.

Documentation pages are long; a method is a few paragraphs inside one. odc show finds those paragraphs — even when the page puts the description beside its heading rather than under it — and sets them for the terminal: signature, headings, lists, tables and highlighted code.

--code
Only the signature and the examples. A cheat sheet in one line.
--raw
Plain text, no colour. Colour also switches off by itself in pipes or with NO_COLOR.
--copy
Straight to the clipboard: wl-copy, xclip, xsel, the system clipboard — or OSC 52, which works over SSH.
--json
Name, kind, signature, code blocks and text, versioned. See § 5.
--width COLS
Wrap at a fixed width instead of the terminal’s.
§ 4The reader

Under 90 columns the reader folds into a single pane. Try narrowing this window.

A reader, not a pager.

Type and the list follows; stop and the page appears. Then stay: follow links inside the docset, jump between sections, search the page, keep what you come back to.

Find in page

Press /, type, and every match lights up; n and N walk through them. Lower case ignores case, upper case doesn’t.

Outline

The page’s headings in a list you can filter. Straight to Examples or Panics without scrolling.

Related

Reading Vec::push? r lists the other 241 symbols of Vec, ready to open.

Favourites and recents

m stars what you are reading; H brings back your stars and your last hundred pages, no search needed.

Links that go somewhere

Tab steps through the links of the page, Enter follows one inside the docset, ⌫ comes back.

Mouse, if you like

Wheel to scroll, click to pick. Drag over text to copy it; double-click for a word, triple for the line.

Every key

While searching

  1. Move through results↑↓
  2. Read the selected entry↵
  3. Pick a docset · a kind^D^T
  4. Favourites and recents^HF2
  5. Star · outline · related^F^O^R
  6. Copy example · open in browser^Y^B
  7. Clear the query, then quitEsc

While reading

  1. Scroll · page · top · endjk␣ggG
  2. Find in page · next · previous/nN
  3. Previous · next section[]
  4. Outline · relatedOr
  5. Next link · follow · backTab↵⌫
  6. Copy example · all · signatureyYs
  7. Star · favourites and recentsmH
  8. Back to search · help · quiti?q
§ 5Tools

The JSON carries a version field, so tools built on it keep working.

Text for pipes. JSON for tools.

Everything the reader shows, a script can ask for. That is how editor integrations are built on odc: they ask, it answers, nothing else to install.

The signature of anything, for a hover or a snippet

$ odc show --json rust:Vec::push
{
  "version": 1,
  "name": "std::vec::Vec::push",
  "kind": "std::vec",
  "docset": "devdocs-rust",
  "signature": "pub fn push(&mut self, value: T)",
  "file_path": "…/devdocs-rust.docset/…/std/vec/struct.vec.html",
  "code_blocks": ["let mut vec = vec![1, 2];\nvec.push(3);\n…"],
  "content": "Appends an element to the back of a collection.\n…"
}

A file to open in a webview, no browser involved

$ odc open --path css:grid
~/.local/share/com.opendoc.app/docsets/CSS.docset/…/grid.html

Candidates for a picker — Telescope, fzf, a command palette

$ odc search --json --limit 50 "$query" | jq -r '.[] | "\(.docset_id)\t\(.name)"'
  • OpenDoc for VS Code

    Search and preview inside the editor. Built on exactly these commands.

  • Your shell

    odc completions zsh > ~/.zfunc/_odc — subcommands and flags on Tab.

  • Anything else

    If it can run a process and read JSON, it can search your docs.

§ 6Environment

Every flag can go before or after the subcommand.

Shares the shelf with the app.

odc reads the docsets folder you chose in OpenDoc, so a docset installed in the app is in the terminal on the next run — and one installed with odc docsets install shows up in the app. No app at all? odc manages the folder on its own. To point it somewhere else:

--docsets DIR
The folder that holds the *.docset bundles. Also OPENDOC_DOCSETS.
--tarix-cache DIR
Where compressed docsets are unpacked. Also OPENDOC_TARIX_CACHE.
ODC_STATE
Where favourites and recents live. By default, cli-state.json in OpenDoc’s data folder.
NO_COLOR
No colour, anywhere. Pipes and redirects get plain text anyway.
PAGER
The pager for long output. less -R when unset.

Exit status

0
Done — including a search with no results, or a picker you cancelled.
1
Something failed: no docsets folder, an unknown docset, a page that couldn’t be read.
2
The command line itself was wrong.
§ 7See also

See also

  • opendoc(1)

    The desktop app: tabs, a docset catalog, one-click installs.

  • opendoc-core

    The engine both share: scanning, indexes, tarix and fuzzy search.

  • opendoc-cli

    Source, issues and release notes for odc.