SwiftSx

A Swift port of sx — multi-engine web search from the command line.

SwiftSx brings sx's multi-backend search to the Swift ecosystem as a reusable library. Like the original Go tool, it queries one or more search backends — SearXNG, Exa, Jina, Brave Search, and Tavily — with automatic fallback when the primary engine is unavailable.

Status: Functional. sx "query" supports all five backends — failover is automatic but follows the configured fallback_engines chain (a default config, or a single API key, queries only the primary) — with JSON/links/plain output, query history, and all filesystem access mediated by a sandbox. It is built to be driven by LLM agents — machine-readable output, sx:-prefixed diagnostics, and stable exit codes. Landing as a stack of small PRs; APIs may still shift before a tagged release.

About the original sx

sx by byteowlz is a Go CLI that lets you search the web from your terminal across multiple engines with automatic failover. Highlights:

• Multiple backends with automatic failover — SearXNG (self-hosted), Exa, Jina, Brave Search, and Tavily
• Search categories — news, images, videos, files
• Filtering — safe search and time-range options
• Scriptable — JSON output
• Content extraction — convert results to Markdown
• Quality of life — query history, shell completions, and interactive mode
• Cross-platform — macOS and Linux

Example sx usage, for reference:

sx "swift concurrency"                 # basic search
sx "swift concurrency" --engine exa    # pick an engine
sx "swift concurrency" -L              # links only
sx "swift concurrency" --text          # extract page content as Markdown
sx history                             # show query history

Command-line usage

The CLI is the sx executable product in this package. From a checkout, run it with swift run sx "swift concurrency"; or build a release binary with swift build -c release and put .build/release/sx on your PATH. The examples below assume sx is on the PATH.

sx "swift concurrency"                  # search (plain, human-readable)
sx "swift concurrency" --json           # JSON envelope (always valid JSON)
sx "swift concurrency" --clean          # JSON with empty/zero fields omitted (still pretty-printed)
sx "swift concurrency" --links          # result URLs only, one per line
sx "swift concurrency" -e brave         # one engine, no fallback
sx "swift concurrency" -n 5             # at most 5 results
sx "swift concurrency" --first          # only the top result
sx "swift concurrency" --site github.com --time-range week
sx "swift concurrency" --first --text   # fetch the top page, output as Markdown
sx "swift concurrency" --first --html   # fetch the top page, output raw HTML
echo "swift concurrency" | sx -         # read the query from stdin
sx "swift concurrency" -o results.json  # write results to a file (sandboxed)
sx "swift concurrency" --dry-run        # show the plan without searching
sx history                              # recent queries
sx history clear                        # delete history

Output is built for programmatic use: machine data on stdout, diagnostics on stderr, and a small, stable set of exit codes to branch on — 0 success, 1 general error, 2 usage, 3 sandbox-refused, 4 empty (with --fail-empty), 7 fail-closed (missing auth / no network — escalate).

Configuration lives at ~/.config/sx/config.toml (or under $XDG_CONFIG_HOME); API keys may also be supplied via BRAVE_API_KEY, TAVILY_API_KEY, EXA_API_KEY, and JINA_API_KEY. Shell completions are generated by sx --generate-completion-script <shell>.

Installation

Add SwiftSx to your Package.swift:

dependencies: [
    .package(url: "https://github.com/PicoMLX/SwiftSx.git", branch: "main")
]

Then add it to a target:

.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "SwiftSx", package: "SwiftSx")
    ]
)

Requires the Swift 6.3 toolchain (Swift language mode v6).

Library usage

The SwiftSx SDK has no ArgumentParser dependency, so hosts (e.g. SwiftBash) can embed the search pipeline directly. All filesystem and environment access goes through the host's ShellKit sandbox.

import SwiftSx

let config = try await Config.load()              // sandboxed TOML + env overrides
let manager = try SearchManager.make(from: config)

var options = config.baseSearchOptions()
options.query = "swift concurrency"

let outcome = try await manager.search(options)   // primary → fallback chain
let json = try ResultRenderer.renderJSON(
    query: options.query, results: outcome.results, clean: true
)

Credits

SwiftSx is a Swift port of sx by byteowlz, used under the MIT License.

License

MIT. See LICENSE.