Skip to content

Using the CLI

For this CLI usage section, no programming knowledge is assumed. We just need to use the slb command in a terminal. If you have not installed it yet, see Installation.

Every command below accepts --help for its own full option list. Most also accept --tui (it needs the tui extra), which opens an interactive form for that command instead of you having to remember its flags. local and mcp are the exceptions. You don't need to give the command its usual argument first:

slb search --tui

The commands, at a glance

Command What it does
search Search the glossary for a query, ranking by relevance.
define Look up one exact term.
compare Look up two or more terms side by side.
related List the terms one definition links to.
terms Fetch every term filed under one topic.
random Pick one or more random terms.
topics List the glossary's topic list.
urls List or fetch from raw glossary term URLs.
sync Check the browser is installed and refresh the local cache.
local Inspect, search, import into, embed, or clear the local cache directly.
install Install, list, remove, or update the browser engine.
config View, edit, and locate the config file.
mcp Run this glossary as an MCP server. See Connecting an AI agent.

The lookup commands (search, define, compare, related, terms, random, topics list and urls list) share the same source model: read locally, live, or both. That's worth understanding once, since it explains a chunk of their flags.

The source model: --local, --live, --auto

Each of them accepts --source local|live|auto, or the equivalent shorthand flags --local, --live, --auto:

  • --local only reads the database on your own machine. Instant, no network, but only finds terms you've already cached there.
  • --live always visits the live glossary through the background browser. Slower, but always current, and does not need anything cached first.

  • --auto (the default) tries local first. For search, this means the local database's best match is scored, and used alone if it's confident enough (--relevance-threshold, default 0.45); otherwise the live site is queried too, and its results are shown first, with the local ones filling in any remaining slots. The other commands have a simpler rule, and it differs a little by command:

    • define uses the local copy only if it has an exact match. Similar terms that happen to be cached don't count, so it goes live (see --suggest in Searching).
    • compare and related check the local copy for each term and go live when it has nothing.
    • terms returns what the local database holds for the topic if it holds anything, and only goes live when it holds nothing. A topic you've only partly cached comes back partly. Use --live, or sync --topic, to get the whole topic.
    • random and topics list read locally if the database has anything (matching the topic, for random), and go live otherwise.
slb search porosity --auto                    # the default: local first, live as a fallback
slb search porosity --local                   # only the local cache, never the network
slb search porosity --live                    # always the live site
slb search porosity --relevance-threshold 0.8 # trust local results less readily

--annotate shows you which source actually answered

search's table (and --json output) can show each result's origin and score as extra columns with --annotate always. Handy the first few times you use --auto, before you have a feel for when it reaches for the live site.

Caching live results: --cache

Whenever a lookup command actually reaches the live glossary (via --live, or --auto falling through to it), the result is saved to the local database by default, so the same lookup is instant next time:

slb search "gas lift"          # --cache is on by default
slb search "gas lift" --no-cache   # look it up live, but do not save it locally

Live results are written incrementally, --cache-batch-size at a time (default 20), rather than all at once at the end. That way, if a large fetch (e.g. slb terms Drilling) gets interrupted partway through, whatever was already fetched is still saved, instead of the whole run being wasted. --cache-on-error (on by default) is what controls whether a failed fetch keeps its partial progress.

Reading this section

  • Searching and Defining Terms

    search, define, compare, related, terms, random, topics, urls, and what output looks like.

    Continue

  • Local Cache and Sync

    sync, the local command group, and install, for working offline.

    Continue

  • Saving, Output and Config Files

    --save, output formats, config, and setting defaults so you do not retype flags.

    Continue