# docsrs-cli
> One-shot stdin/stdout CLI for crates.io and docs.rs documentation for LLM agents.
docsrs-cli is a born-execute-finalize-die binary that searches crates, fetches README overviews and typed rustdoc items, and emits stable JSON envelopes on stdout with diagnostics only on stderr. Current release line is 1.3.x (release 1.3.0) with method fail-closed (`#method.X` missing → `not_found` exit 66), error envelopes carrying `command`+`duration_ms`, hard-max budget fail-closed (exit 65), ranked `--match` modes, effective-URL `--page-token` echo, cascade `--suggest` (method leaves from parent page), hyphen path normalize, rustdoc chrome scrub, doctor `ok` parity, timeout-0 fail-closed, `schema --cmd all` (20 wire names), and `data.cache_hit`.
## Command Surface
- Data: `search-crates`, `readme`, `get-item`, `search-in-crate`
- Discovery: `version`, `doctor`, `commands`, `schema`, `completions`
- Storage: `cache path`, `cache stats`, `cache clear`
- Configuration: `config path`, `config show`, `config init`
- Eleven top-level commands, seventeen invocable paths counting subcommands
## Payload Reduction
- Eight global flags cut the JSON envelope before it is written, so no jq stage is needed
- `--select KEYS` projects dotted keys (alias `--fields`); missing keys are skipped, never null
- `--filter EXPR` keeps elements matching `key=value`, `key!=value`, `key~substring`; repeat for AND
- `--sort-by KEY` sorts ascending; elements without the key go last
- `--dedupe-by KEY` drops later elements repeating the value
- `--max-items N` bounds the EMISSION; `search-in-crate --limit` bounds the query
- `--count-only` replaces the payload with `{"count": N}`
- `--truncate-content N` shortens strings above N characters, never splitting UTF-8
- `--max-output-bytes N` caps the emitted payload; hard max 2097152
- Fixed order: filter, sort-by, dedupe-by, max-items, select, count-only, truncate-content, max-output-bytes
- Read `agent_surface` for `input_count`, `output_count`, `limited`, `content_truncated`, `output_truncated`
## Primary Documentation
- [README](README.md): product landing page, install, commands, and why no product env var is read
- [Configuration](docs/CONFIGURATION.md): every global flag and every `config.toml` key
- [How to use](docs/HOW_TO_USE.md): first command in 60 seconds
- [Agents](docs/AGENTS.md): agent integration contract and economy
- [Cookbook](docs/COOKBOOK.md): executable recipes
- [Cross platform](docs/CROSS_PLATFORM.md): OS matrix and XDG paths
- [Migration](docs/MIGRATION.md): upgrade notes through 1.3.0
- [Testing](docs/TESTING.md): how to run categorized tests and smoke-live
- [JSON schemas](docs/schemas/README.md): machine-readable payload contracts (20 offline files)
- [Integrations](INTEGRATIONS.md): agents, shells, CI surfaces
- [Changelog](CHANGELOG.md): Keep a Changelog history including 1.3.0
- [Security](SECURITY.md): vulnerability reporting
- [Contributing](CONTRIBUTING.md): contributor workflow
- [English skill](skills/docsrs-cli-en/SKILL.md): imperative agent runbook (MUST reject method+item_page)
- [Portuguese skill](skills/docsrs-cli-pt/SKILL.md): runbook em português
- [Full index](llms-full.txt): expanded documentation map
- [Portuguese discovery](llms.pt-BR.txt): mapa em português
- [gaps.md](gaps.md): product gap matrix (Camada Y closes W+X; OPEN W+X = 0)
## Optional
- [get-item schema](docs/schemas/get-item.schema.json): item_name, resolved_version, extraction=method on success, anchor_family (real rustdoc anchor family), cache_hit
- [search-in-crate schema](docs/schemas/search-in-crate.schema.json): match_mode, score, cache_hit
- [search-crates schema](docs/schemas/search-crates.schema.json): page tokens, effective echo, cache_hit
- [readme schema](docs/schemas/readme.schema.json): resolved_version and cache_hit
- [schema meta](docs/schemas/schema.schema.json): embedded schema document payload
- [completions schema](docs/schemas/completions.schema.json): shell + script JSON mode
- [error schema](docs/schemas/error.schema.json): command, duration_ms, budget kind, retryable flag, structured suggestions array
- [dry-run schema](docs/schemas/dry-run.schema.json): planned_url, validation, planned_params.crate_name