CLI

Authorize with OAuth 2.1, then search the web, read pages and check trends from your terminal.

s1 puts the whole API in your terminal — and, because it prints JSON on demand, in your shell scripts too.

Install

curl -fsSL https://cli.search1api.com/install.sh | bash

That installs a standalone binary; no Node.js required. If you would rather use npm:

npm install -g search1api-cli

Log in

s1 login

This is an OAuth 2.1 login, not an API-key handoff. The CLI:

Discovers Search1API's authorization server.
Dynamically registers itself as a public native client.
Opens the authorization page with Authorization Code + PKCE (S256).
Saves the resulting access and refresh tokens in its local configuration.
Refreshes the access token automatically when it expires.

The account owner still signs in and approves the connection in the browser. Run s1 config show afterward to confirm that the active authentication method is OAuth 2.1.

If the CLI cannot open a browser automatically, print the authorization URL instead:

s1 login --no-browser

The redirect must still be able to reach the loopback callback on the machine running s1.

API key fallback

Existing API keys remain supported for scripts, CI, and environments where an interactive OAuth login is not practical:

s1 config set-key YOUR_API_KEY
# or
export SEARCH1API_KEY=YOUR_API_KEY

SEARCH1API_KEY takes precedence over saved OAuth credentials. Remove it when you want the CLI to use the OAuth tokens created by s1 login. See Authentication for the complete OAuth and API-key model.

Commands

Command	What it does
`s1 search "<query>"`	Search the web
`s1 news "<query>"`	Search the news
`s1 crawl <url>`	Read a page
`s1 sitemap <url>`	List a site's links
`s1 trending <github\|hackernews>`	Trending topics
`s1 balance`	Remaining credits
`s1 login`	Authorize with OAuth 2.1 in the browser
`s1 config set-key \| show`	Manage configuration
`s1 update`	Update `s1` in place

Examples

# Five results from Google
s1 search "rust async" -n 5 -s google

# Search, then crawl the top 3 results for their full text
s1 search "web framework" -c 3

# Today's news, from Hacker News
s1 news "tech layoffs" -s hackernews -t day

# Machine-readable output, straight into jq
s1 search "test" --json | jq '.results[0].title'

The --json flag is what makes s1 scriptable: pipe it into jq, feed it to a model, commit it to a file.

Flags worth knowing

Flag	Meaning
`-n, --max-results`	1–50, defaults to 10
`-s, --service`	Pick an engine; omit to race several
`-c, --crawl <N>`	Crawl the top N results for full text
`--include` / `--exclude`	Restrict or exclude sites
`-t, --time <day\|month\|year>`	Time range
`--json`	Raw JSON instead of formatted output

-c/--crawl is the same deep-search feature as the API's crawl_results, and bills the same way: 1 credit for the search plus 1 per page successfully crawled. See Credits and limits.

The retired s1 reasoning and s1 models commands were removed in CLI 1.2.3.

Source: github.com/superagents-lab/search1api-cli