name	smart-search-cli
description	CLI-first web research and source retrieval through the local smart-search command. Use when Codex needs current web search, source-backed fact checking, URL fetching, site mapping, official/API/documentation search, deep research, or reproducible search evidence via Skill + CLI instead of MCP tools or native web search.

Smart Search CLI

Use the local smart-search command as the default execution layer for web research. This entrypoint keeps only routing, boundaries, and reference selection; load the focused reference file when command details or provider contracts matter.

Default Workflow

Run smart-search doctor --format json when configuration or availability is uncertain.
If doctor reports missing configuration, use smart-search setup or smart-search config set KEY VALUE when the user provides keys. Do not ask users to edit global environment variables by default.
If OpenAI-compatible search hangs or times out after doctor succeeds, run smart-search diagnose openai-compatible --format markdown and use its summary.
If doctor returns ok: true, use only smart-search CLI subcommands for web research. Do not call Codex native web search in the same task.
Use smart-search skills status --targets codex --format json when the installed global skill may be stale; use smart-search skills update --targets codex --format json to refresh it without rerunning setup.
Use smart-search smoke --mock --format json after CLI/provider architecture changes. Use --live only when real keys are available and the user expects live checks.
Preserve command lines and source URLs in your answer. Prefer citing fetched pages or primary_sources; treat extra_sources as follow-up candidates until fetched.

Routing

search: first hop for realtime, broad exploration, community signals, multi-source summaries, and routing metadata.
route: explain capability routing without executing providers.
research: live Deep Research executor for end-to-end plan, discovery, fetch/read, gap check, and evidence-only synthesis.
deep: offline Deep Research planner; it does not run providers, fetch pages, or replace default search.
zhipu-search: Chinese-language, domestic China, policy/regulatory, announcements, current news, or China-local source discovery.
context7-library / context7-docs: library, SDK, API, framework, or documentation intent. Prefer Context7 before Exa for docs/API questions.
exa-search: official domains, papers, product pages, trusted pages, date/domain-filtered low-noise discovery, and adjacent source discovery through exa-similar.
fetch: user-provided URLs or any claim that depends on page content.
map: documentation site or domain structure before fetching many pages from one site.
anysearch-*: explicit experimental vertical search only. Inspect domains first and do not use AnySearch as default fallback.
model current: inspect explicit provider models only. Change models with smart-search config set XAI_MODEL ... or smart-search config set OPENAI_COMPATIBLE_MODEL ....

Key Boundaries

smart-search should resolve from the user's PATH.
Private API keys should be saved with smart-search setup or smart-search config set; environment variables remain supported for CI and advanced users.
In sandboxed runtimes, set SMART_SEARCH_CONFIG_DIR to an absolute writable path when the default config directory is unavailable or must be pinned.
The standard minimum profile requires one configured provider in each of main_search, docs_search, and fetch capability. Missing required capabilities are hard configuration failures.
Fallback must remain same-capability only. Do not use Context7 for broad news/web facts or page-extraction providers as documentation search replacements.
xAI Responses and OpenAI-compatible are peer main_search providers. Do not reuse one provider's URL/key to fabricate the other provider as fallback.
For current-news, policy, finance, health, and other high-risk facts, do not answer from broad search.content alone. Fetch key pages and summarize only what fetched text supports.
Native web_search is disabled in this CLI-first workflow unless the user explicitly configures another approved route; do not silently fall back to another web-search route.

References

Command examples, evidence files, timeout retry policy, and guardrails: references/command-patterns.md
Deep Research planner/executor workflow, plan fields, gap check, and smoke matrix: references/deep-research-mode.md
CLI entrypoints, command signatures, aliases, output fields, exit codes, and tool policy: references/cli-core.md
Setup, config storage, skill installation, provider endpoints, and OpenAI-compatible diagnostics: references/setup-config.md
Intent routing, provider capabilities, source provenance, fallback boundaries, and routing maintenance: references/provider-routing.md
Regression, packaged install checks, release lanes, and release closeout lessons: references/regression-release.md
Compatibility reference map for older instructions that mention the original monolithic file: references/cli-contract.md

Smart Search CLI

Default Workflow

Run smart-search doctor --format json when configuration or availability is uncertain.

If doctor reports missing configuration, use smart-search setup or smart-search config set KEY VALUE when the user provides keys. Do not ask users to edit global environment variables by default.

If OpenAI-compatible search hangs or times out after doctor succeeds, run smart-search diagnose openai-compatible --format markdown and use its summary.

If doctor returns ok: true, use only smart-search CLI subcommands for web research. Do not call Codex native web search in the same task.

Use smart-search skills status --targets codex --format json when the installed global skill may be stale; use smart-search skills update --targets codex --format json to refresh it without rerunning setup.

Use smart-search smoke --mock --format json after CLI/provider architecture changes. Use --live only when real keys are available and the user expects live checks.

Preserve command lines and source URLs in your answer. Prefer citing fetched pages or primary_sources; treat extra_sources as follow-up candidates until fetched.

Routing

search: first hop for realtime, broad exploration, community signals, multi-source summaries, and routing metadata.

route: explain capability routing without executing providers.

research: live Deep Research executor for end-to-end plan, discovery, fetch/read, gap check, and evidence-only synthesis.

deep: offline Deep Research planner; it does not run providers, fetch pages, or replace default search.

zhipu-search: Chinese-language, domestic China, policy/regulatory, announcements, current news, or China-local source discovery.

context7-library / context7-docs: library, SDK, API, framework, or documentation intent. Prefer Context7 before Exa for docs/API questions.

exa-search: official domains, papers, product pages, trusted pages, date/domain-filtered low-noise discovery, and adjacent source discovery through exa-similar.

fetch: user-provided URLs or any claim that depends on page content.

map: documentation site or domain structure before fetching many pages from one site.

anysearch-*: explicit experimental vertical search only. Inspect domains first and do not use AnySearch as default fallback.

model current: inspect explicit provider models only. Change models with smart-search config set XAI_MODEL ... or smart-search config set OPENAI_COMPATIBLE_MODEL ....

Key Boundaries

smart-search should resolve from the user's PATH.

Private API keys should be saved with smart-search setup or smart-search config set; environment variables remain supported for CI and advanced users.

In sandboxed runtimes, set SMART_SEARCH_CONFIG_DIR to an absolute writable path when the default config directory is unavailable or must be pinned.

The standard minimum profile requires one configured provider in each of main_search, docs_search, and fetch capability. Missing required capabilities are hard configuration failures.

Fallback must remain same-capability only. Do not use Context7 for broad news/web facts or page-extraction providers as documentation search replacements.

xAI Responses and OpenAI-compatible are peer main_search providers. Do not reuse one provider's URL/key to fabricate the other provider as fallback.

For current-news, policy, finance, health, and other high-risk facts, do not answer from broad search.content alone. Fetch key pages and summarize only what fetched text supports.

Native web_search is disabled in this CLI-first workflow unless the user explicitly configures another approved route; do not silently fall back to another web-search route.

References

Command examples, evidence files, timeout retry policy, and guardrails: references/command-patterns.md

Deep Research planner/executor workflow, plan fields, gap check, and smoke matrix: references/deep-research-mode.md

CLI entrypoints, command signatures, aliases, output fields, exit codes, and tool policy: references/cli-core.md

Setup, config storage, skill installation, provider endpoints, and OpenAI-compatible diagnostics: references/setup-config.md

Intent routing, provider capabilities, source provenance, fallback boundaries, and routing maintenance: references/provider-routing.md

Regression, packaged install checks, release lanes, and release closeout lessons: references/regression-release.md

Compatibility reference map for older instructions that mention the original monolithic file: references/cli-contract.md

smart-search-cli

Smart Search CLI

Default Workflow

Routing

Key Boundaries

References

Smart Search CLI

Default Workflow

Routing

Key Boundaries

References