Metadata-Version: 2.4
Name: cheap-search
Version: 2026.5.17
Summary: Lightweight, agent-facing CLI for provider-specific search (Grok web/X, local Codex)
Author-email: Qian Zhang <contact@qzsh.email>
License: MIT License
        
        Copyright (c) 2026 Qian Zhang
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,ai,cli,codex,grok,llm,search,xai
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.13
Requires-Dist: typer>=0.20.0
Requires-Dist: xai-sdk>=1.0
Description-Content-Type: text/markdown

# cheap-search

Lightweight, agent-facing CLI for provider-specific search. Wraps two backends behind one binary and ships two Claude Skills that teach a coding agent *when* and *how* to call it.

```
cheap-search
├── grok-search   # xAI / Grok — web + X (Twitter)
└── codex-search  # local Codex CLI passthrough
```

The agent picks the provider explicitly. There is no automatic routing.

## Why

Built-in agent search (Claude WebSearch, etc.) is fine for generic lookups. `cheap-search` exists for the cases where you specifically want **Grok's view of the web**, **Grok's read of X/Twitter**, or **Codex's grounding** — and you want the agent to invoke the provider you asked for, not pick one for you.

## Install

### macOS (Apple Silicon) / Linux (x64, arm64)

```bash
curl -fsSL https://raw.githubusercontent.com/AirswitchAsa/cheap-search/main/scripts/install.sh | sh
```

### Anywhere with Python 3.13

```bash
uv tool install cheap-search       # or: pip install cheap-search
```

### Ephemeral (no install)

```bash
uvx --from cheap-search cheap-search --help
```

## Configure

Grok needs an xAI API key. Either:

```bash
export XAI_API_KEY=xai-...
```

or persist it locally with the CLI (stores at `~/.config/cheap-search/config.toml`, mode `0600`):

```bash
cheap-search grok apikey set        # prompts with hidden input
echo "$KEY" | cheap-search grok apikey set -
cheap-search grok apikey status
cheap-search grok apikey unset
```

Env wins when both are set.

Codex handles its own auth — `codex login` once.

## Use

```bash
cheap-search grok web "latest stable Python release"
cheap-search grok x   "xAI announcements" --from 2026-05-01
cheap-search codex    "look up the OpenAI Responses API web search syntax"

cheap-search doctor          # verify local setup
cheap-search providers       # list supported providers
```

Pass `-o json` for agent-parsable output:

```json
{
  "answer": "…",
  "model": "grok-4.3",
  "tool_kind": "web",
  "citations": [{"url": "https://…", "title": "…"}]
}
```

For codex, trailing args after `--` are forwarded:

```bash
cheap-search codex "<query>" -- --skip-git-repo-check -m gpt-5-codex
```

## Skills

Two skills under [`skills/`](skills/):

- [`grok-search`](skills/grok-search/SKILL.md) — fires only when the user explicitly names Grok / xAI / X / Twitter.
- [`codex-search`](skills/codex-search/SKILL.md) — fires only when the user explicitly names Codex.

Each skill bundles `scripts/ensure-cheap-search.sh` which resolves the bundled binary, falls back to `uvx --from cheap-search cheap-search`, and only complains if neither is available.

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Usage error |
| 2 | Missing configuration (no API key / no `codex` binary) |
| 3 | Provider failure (network, 4xx/5xx, codex non-zero) |

Agents can branch on these to choose between "tell user to configure" and "surface stderr."

## Specification

The behavioral contract lives as a [DOG](https://github.com/AirswitchAsa/dog) document graph under [`docs/`](docs/). Browse the [project index](docs/index.dog.md) for actors, behaviors, components, and data definitions. The implementation is built to match — lint stays clean: `dog lint docs`.

## Development

```bash
git clone https://github.com/AirswitchAsa/cheap-search
cd cheap-search
uv sync

# Unit tests (no network):
uv run pytest -m "not live"

# Full matrix incl. live xAI + codex calls (costs ~$0.10 in xAI tool fees):
echo 'XAI_API_KEY=xai-...' > .env
uv run pytest
```

CI is build-only (manual `workflow_dispatch`); tests are run locally with a real API key. See [`.github/workflows/release.yml`](.github/workflows/release.yml).

## License

MIT. See [LICENSE](LICENSE).
