.Dd December 7, 2025
.Dt SO 1
.Os
.Sh NAME
.Nm so
.Nd terminal interface for StackOverflow
.Sh SYNOPSIS
.Nm
.Op Fl -list-sites
.Op Fl -update-sites
.Op Fl -set-api-key Ar key
.Op Fl s | Fl -site Ar site-code
.Op Fl l | Fl -limit Ar int
.Op Fl -lucky | Fl -no-lucky
.Op Fl e | Fl -search-engine Ar engine
.Ar query ...
.Sh DESCRIPTION
.Nm
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.
.Pp
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.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl -list-sites
Print a table of all available StackExchange sites with their site codes
and URLs.
.It Fl -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.
.It Fl -set-api-key Ar key
Set the StackExchange API key for authenticated requests.
This increases the API rate limit.
See
.Sx API KEYS
for more information.
.It Fl s Ar site-code , Fl -site Ar 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
.Cm stackoverflow ,
.Cm askubuntu ,
.Cm unix ,
.Cm tex ,
and
.Cm serverfault .
Use
.Fl -list-sites
to see all available sites.
Default: configured sites or
.Cm stackoverflow .
.It Fl l Ar int , Fl -limit Ar int
Set the maximum number of questions to retrieve.
Default: 20.
.It Fl -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
.Sy SPACE
to enter the full TUI,
.Sy o
to open the answer in a browser, or any other key to exit.
.It Fl -no-lucky
Disable lucky mode if it is enabled by default in the configuration file.
.It Fl e Ar engine , Fl -search-engine Ar engine
Specify which search engine to use for finding relevant questions.
Valid values are:
.Cm duckduckgo ,
.Cm google ,
or
.Cm stackexchange .
.Pp
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.
.El
.Sh EXAMPLES
Search StackOverflow with default configuration:
.Pp
.Dl $ so how do i reverse a list in python
.Pp
Search for a LaTeX solution on tex.stackexchange.com:
.Pp
.Dl $ so --site tex how to put tilde over character
.Pp
Search multiple sites using Google as the search engine:
.Pp
.Dl $ so -e google -s askubuntu -s stackoverflow -s unix how do i install linux
.Pp
Get the top answer immediately using lucky mode:
.Pp
.Dl $ so --lucky how to exit vim
.Pp
List all available StackExchange sites:
.Pp
.Dl $ so --list-sites
.Pp
Set a StackExchange API key:
.Pp
.Dl $ so --set-api-key YOUR_API_KEY_HERE
.Sh CONFIGURATION
.Nm
uses configuration files to store default settings at
.Pa ~/.config/so/
.Pp
To print the configuration file path:
.Pp
.Dl $ so --print-config-path
.Pp
The configuration file is in YAML format and supports the following options:
.Bl -tag -width "search_engine"
.It Sy api_key
StackExchange API key (default: built-in key)
.It Sy limit
Number of questions to retrieve (default: 20)
.It Sy lucky
Enable lucky mode by default (default: true)
.It Sy sites
List of default StackExchange sites to search
.It Sy search_engine
Default search engine
.Cm ( duckduckgo ,
.Cm google ,
or
.Cm stackexchange )
.It Sy copy_cmd
Command for copying to system clipboard (default:
.Cm xclip )
.El
.Pp
Example configuration at
.Pa ~/.config/so/config.yml
.Bd -literal -offset indent
---
api_key: ~
limit: 20
lucky: true
sites:
  - stackoverflow
  - askubuntu
search_engine: google
copy_cmd: xclip
.Ed
.Sh THEMES
Color themes can be customized by editing the
.Pa colors.toml
file in the configuration directory.
Sample themes are available in the upstream repository.
.Sh API KEYS
.Nm
includes a built-in StackExchange API key for convenience.
Users can optionally set their own API key to avoid shared rate limits.
.Pp
To obtain an API key:
.Bl -enum -compact
.It
Visit https://api.stackexchange.com/docs
.It
Register an application
.It
Set the key using
.Fl -set-api-key
.El
.Pp
Without an API key, the StackExchange API allows 300 requests per day per
IP address.
With a key, this limit is significantly increased.
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr xclip 1
.Sh AUTHORS
.An -nosplit
.Nm
was written by
.An Sam Tay Aq Mt sam.chong.tay@pm.me .
.Pp
This manual page was written by
.An Nadzeya Hutsko Aq Mt nadzya.info@gmail.com
.Sh BUGS
Bug reports and feature requests can be submitted at:
.Lk https://github.com/samtay/so/issues
.Pp
Known limitations:
.Bl -bullet -compact
.It
DuckDuckGo may occasionally block requests; use Google or StackExchange
search engines as alternatives
.It
Searching more than 30 sites simultaneously may trigger StackExchange API
rate limiting
.It
Some terminal emulators may not properly render all Unicode characters used
in markdown content
.El