NAME¶

so — terminal interface for StackOverflow

SYNOPSIS¶

DESCRIPTION¶

so is a terminal-based interface to the StackExchange network that allows searching and browsing StackOverflow questions and answers directly from the command line. It provides a fast, intuitive text user interface (TUI) for developers who prefer working in the terminal.

The tool supports searching any site in the StackExchange network including StackOverflow, AskUbuntu, Unix & Linux, TeX, and many others. Results can be filtered by site, and searches can be performed using either Google, DuckDuckGo, or StackExchange's native search as the backend.

The options are as follows:

--list-sites

Print a table of all available StackExchange sites with their site codes and URLs.

--update-sites

Update the local cache of StackExchange sites. Use this if a site code is not recognized or if new sites have been added to the StackExchange network.

--set-api-key key

Set the StackExchange API key for authenticated requests. This increases the API rate limit. See API KEYS for more information.

-s site-code, --site site-code

Specify a StackExchange site to search. This option can be specified multiple times to search across multiple sites simultaneously. Common site codes include stackoverflow, askubuntu, unix, tex, and serverfault. Use --list-sites to see all available sites. Default: configured sites or stackoverflow.

-l int, --limit int

Set the maximum number of questions to retrieve. Default: 20.

--lucky

Display only the top-voted answer from the most relevant question, similar to Google's "I'm Feeling Lucky" feature. After displaying the answer, the user can press SPACE to enter the full TUI, o to open the answer in a browser, or any other key to exit.

--no-lucky

Disable lucky mode if it is enabled by default in the configuration file.

-e engine, --search-engine engine

Specify which search engine to use for finding relevant questions. Valid values are: duckduckgo, google, or stackexchange.

StackExchange search is the fastest as it requires no HTML parsing, but provides the most basic search functionality. DuckDuckGo is the default but may occasionally block requests. Google provides comprehensive search but is slower due to larger response sizes.

EXAMPLES¶

Search StackOverflow with default configuration:

Search for a LaTeX solution on tex.stackexchange.com:

Search multiple sites using Google as the search engine:

Get the top answer immediately using lucky mode:

List all available StackExchange sites:

Set a StackExchange API key:

CONFIGURATION¶

so uses configuration files to store default settings at ~/.config/so/

To print the configuration file path:

The configuration file is in YAML format and supports the following options:

api_key

StackExchange API key (default: built-in key)

limit

Number of questions to retrieve (default: 20)

lucky

Enable lucky mode by default (default: true)

sites

List of default StackExchange sites to search

search_engine

Default search engine (duckduckgo, google, or stackexchange)

copy_cmd

Command for copying to system clipboard (default: xclip)

Example configuration at ~/.config/so/config.yml

---
api_key: ~
limit: 20
lucky: true
sites:
  - stackoverflow
  - askubuntu
search_engine: google
copy_cmd: xclip

THEMES¶

Color themes can be customized by editing the colors.toml file in the configuration directory. Sample themes are available in the upstream repository.

API KEYS¶

so includes a built-in StackExchange API key for convenience. Users can optionally set their own API key to avoid shared rate limits.

To obtain an API key:

1. Visit https://api.stackexchange.com/docs
2. Register an application
3. Set the key using --set-api-key

Without an API key, the StackExchange API allows 300 requests per day per IP address. With a key, this limit is significantly increased.

EXIT STATUS¶

The so utility exits 0 on success, and >0 if an error occurs.

SEE ALSO¶

xclip(1)

AUTHORS¶

so was written by Sam Tay <sam.chong.tay@pm.me>.

This manual page was written by Nadzeya Hutsko <nadzya.info@gmail.com>

BUGS¶

Bug reports and feature requests can be submitted at: https://github.com/samtay/so/issues

Known limitations:

• DuckDuckGo may occasionally block requests; use Google or StackExchange search engines as alternatives
• Searching more than 30 sites simultaneously may trigger StackExchange API rate limiting
• Some terminal emulators may not properly render all Unicode characters used in markdown content