SO(1)

NAME
so - terminal interface for StackOverflow

SYNOPSIS
so [--list-sites] [--update-sites] [--set-api-key key] [-s | --site site-code] [-l | --limit int] [--lucky | --no-lucky] [-e | --search-engine engine] query ...

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:

    $ so how do i reverse a list in python

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

    $ so --site tex how to put tilde over character

Search multiple sites using Google as the search engine:

    $ so -e google -s askubuntu -s stackoverflow -s unix how do i install linux

Get the top answer immediately using lucky mode:

    $ so --lucky how to exit vim

List all available StackExchange sites:

    $ so --list-sites

Set a StackExchange API key:

    $ so --set-api-key YOUR_API_KEY_HERE

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

To print the configuration file path:

    $ so --print-config-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

SEE ALSO
xclip(1)

AUTHORS
-nosplit 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