[Português (pt-BR)](COOKBOOK.pt-BR.md)
# Cookbook
> Copy a recipe, run the command, read the JSON.
## Latency Note
- Cold network fetches depend on crates.io and docs.rs latency
- Warm cache hits stay local inside TTL and report `cache_hit: true`
- Use `--dry-run` when you only need planned URLs
## Default Values Reference
- Timeout wall-clock defaults to a product-safe second budget via config
- Cache TTL defaults to 86400 seconds
- Cache soft budget defaults to 256 MiB
- Max body defaults to 10 MiB hard ceiling (values above hard max fail closed with exit 65)
- Max output defaults to 2 MiB hard ceiling (values above hard max fail closed with exit 65)
- `search-in-crate --match` defaults to `prefix`
- `search-in-crate --limit` defaults to 100 and clamps at 1000
- JSON auto-selects on non-TTY stdout (except raw `completions`)
## How To Search for a Crate
- Problem: find crates matching a keyword
```bash
docsrs-cli search-crates serde --json
docsrs-cli search-crates async --page 1 --per-page 20 --sort downloads --json
```
## How To Paginate With page-token
- Problem: walk crates.io results without hand-building query strings
```bash
docsrs-cli search-crates async --page 1 --per-page 20 --json
docsrs-cli search-crates --page-token "$NEXT" --json
docsrs-cli --dry-run search-crates --page-token '?q=serde&per_page=2&page=2' --json
```
## How To Fetch a Crate Overview
- Problem: read the docs.rs overview for a crate
```bash
docsrs-cli readme tokio --json
docsrs-cli readme clap --crate-version 4.5.0 --json
docsrs-cli readme tokio --crate-version latest --json
```
## How To Fetch stdlib Overview
- Problem: get std/core/alloc channel docs without guessing HTML
```bash
docsrs-cli readme std --json
docsrs-cli readme core --json
docsrs-cli readme alloc --json
```
## How To Observe Limit Clamp Offline
- Problem: prove search-in-crate --limit hard clamp without network
```bash
docsrs-cli --dry-run search-in-crate tokio "" --limit 5000 --json
```
## How To Fetch a Typed Item
- Problem: pull documentation for one struct, trait, or function
```bash
docsrs-cli get-item serde trait Serialize --json
docsrs-cli get-item tokio struct runtime::Runtime --json
docsrs-cli get-item clap trait clap::Parser --json
docsrs-cli get-item async-trait attribute async_trait --json
```
## How To Resolve Associated Methods
- Problem: open method docs such as `Runtime::new` without guessing HTML
```bash
docsrs-cli get-item tokio method runtime::Runtime::new --json
docsrs-cli get-item tokio fn runtime::Runtime::new --json
```
## How To Open a Trait Associated Item
- Problem: `Iterator::Item` and `Duration::MAX` have no page of their own
```bash
docsrs-cli get-item std type iter::Iterator::Item --json
docsrs-cli get-item std const time::Duration::MAX --json
docsrs-cli get-item std method iter::Iterator::next --json
docsrs-cli get-item std const u32::MAX --json
docsrs-cli get-item std type iter::Iterator::item --suggest --json
```
## How To Open an Enum Variant or a Struct Field
- Problem: `Option::Some` and `Range::start` exist only as anchors on the parent
```bash
docsrs-cli get-item std variant option::Option::Some --json
docsrs-cli get-item std variant result::Result::Ok --json
docsrs-cli get-item std structfield ops::Range::start --json
docsrs-cli get-item std field ops::Range::end --json
docsrs-cli get-item std variant Some --json
docsrs-cli get-item std variant option::Option::some --suggest --json
```
## How To Steer Diagnostics Without an Environment Variable
- Problem: the product reads no product env var, so `RUST_LOG` has no effect
```bash
docsrs-cli -v version docsrs-cli config init docsrs-cli config show --json | jaq -r '.data.log_directive // "unset"'
docsrs-cli -q version ```
## How To Recover From a Method Typo
- Problem: agent typed `Runtime::neww` and must not accept a parent-page false success
```bash
docsrs-cli get-item tokio method Runtime::neww --suggest --json
docsrs-cli get-item tokio method Runtime::neww --suggest --json \
| jaq -r '.error.suggestions[0] | "docsrs-cli get-item tokio \(.kind) \(.path) --json"'
```
## How To Plan a Method URL Offline
- Problem: inspect planned parent kind and probes without network
```bash
docsrs-cli --dry-run get-item tokio method runtime::Runtime::neww --json
```
## How To Fail Closed on Budget Hard Max Overshoot
- Problem: agent must not accept silent clamp when flags exceed hard max
```bash
docsrs-cli --max-body-bytes 999999999 version --json
docsrs-cli --max-output-bytes 999999999 version --json
```
## How To Reduce Payload Without a JSON Post-Processor
- Problem: agent context is expensive and the full envelope is larger than the answer
```bash
docsrs-cli --dry-run --select planned_url readme serde --json
docsrs-cli --dry-run --fields planned_url readme serde --json
docsrs-cli --dry-run --count-only readme serde --json
docsrs-cli --dry-run --truncate-content 5 readme serde --json
docsrs-cli --dry-run --select nope readme serde --json
docsrs-cli --select name search-in-crate serde Serialize --limit 3 --json
docsrs-cli --dedupe-by name search-in-crate serde Serialize --limit 5 --json
```
## How To Take the Top N of a Filtered Set
- Problem: `--filter` narrows the list but the answer is still the first few rows
- Wrong instinct: pipe the envelope through `jaq` — that puts the work back on the agent
```bash
docsrs-cli --filter kind=struct --sort-by name --max-items 5 --select name \
search-in-crate serde "" --limit 200 --json
docsrs-cli --sort-by downloads search-crates serde --per-page 20 --json
docsrs-cli --sort-by no_such_key search-crates serde --json
docsrs-cli --max-items 5 --count-only search-in-crate serde "" --limit 200 --json
docsrs-cli --max-items 999 search-in-crate serde "" --limit 20 --json
```
## How To Trust the Counters After a Reduction
- Problem: `emitted` is documented as hits actually emitted, and reduction shrinks the array
```bash
docsrs-cli --filter kind=struct search-in-crate serde "" --limit 200 --json
docsrs-cli schema --cmd agent-surface --json
```
## How To Fail Closed on a Malformed Filter
- Problem: a typo in a filter must never look like an honest empty result
```bash
docsrs-cli --dry-run --filter 'key without operator' readme serde --json
docsrs-cli --dry-run --filter '=novalue' readme serde --json
docsrs-cli --dry-run --filter 'command=readme' --filter 'ok!=false' readme serde --json
```
## How To Confirm Rustdoc Chrome Scrub
- Problem: markdown must not carry rustdoc UI chrome into agent context
```bash
docsrs-cli readme serde --json
```
## How To Pass Hyphenated item_path Segments
- Problem: crates.io style names use hyphens but rustc paths use underscores
```bash
docsrs-cli --dry-run get-item async-trait attribute async-trait --json
docsrs-cli get-item async-trait attribute async-trait --json
```
## How To Suggest Nearby Symbols on 404
- Problem: recover from a wrong item path without scraping all.html yourself
```bash
docsrs-cli get-item serde struct Serde --suggest --json
docsrs-cli get-item tokio struct RuntimeX --suggest --json
```
## How To Handle Body Budget Without Retry Storms
- Problem: a response exceeds `--max-body-bytes` and agents must not spin
```bash
docsrs-cli --max-body-bytes 50 readme serde --json
```
## How To Fail Closed on Explicit Zero Timeouts
- Problem: prove timeout 0 is rejected instead of hanging forever
```bash
docsrs-cli --timeout 0 version --json
docsrs-cli --connect-timeout 0 doctor --json
```
## How To Search Symbols Inside One Crate
- Problem: locate symbols without browsing HTML
```bash
docsrs-cli search-in-crate reqwest Client --json
docsrs-cli search-in-crate clap Parser --item-type trait --json
docsrs-cli search-in-crate tokio "" --limit 50 --json
```
- Filter by the kind the symbol actually is: `Parser` in clap is a trait and a derive macro, never a function
- A filter that matches nothing is still a success: exit `0` with `total` and `emitted` at `0`, not an error
- The echoed `item_type` is the canonical spelling, so `--item-type function` comes back as `fn`
## How To Choose Match Modes
- Problem: tighten or relax symbol search ranking
```bash
docsrs-cli search-in-crate serde Serialize --match exact --json
docsrs-cli search-in-crate serde Ser --match prefix --json
docsrs-cli search-in-crate serde de --match substring --limit 20 --json
```
## How To Detect cache_hit
- Problem: know whether a payload came from local disk cache
```bash
docsrs-cli readme serde --json
docsrs-cli readme serde --json
docsrs-cli --no-cache readme serde --json
docsrs-cli cache path --json
docsrs-cli cache stats --json
```
## How To Discover Agent Surface
- Problem: learn commands and payload shapes programmatically
```bash
docsrs-cli commands --json
docsrs-cli schema --cmd get-item --json
docsrs-cli schema --cmd search-crates --json
docsrs-cli schema --cmd readme --json
docsrs-cli schema --cmd search-in-crate --json
docsrs-cli schema --cmd version --json
docsrs-cli schema --cmd doctor --json
docsrs-cli schema --cmd commands --json
docsrs-cli schema --cmd cache --json
docsrs-cli schema --cmd cache-path --json
docsrs-cli schema --cmd cache-clear --json
docsrs-cli schema --cmd cache-stats --json
docsrs-cli schema --cmd config --json
docsrs-cli schema --cmd config-path --json
docsrs-cli schema --cmd config-show --json
docsrs-cli schema --cmd config-init --json
docsrs-cli schema --cmd schema --json
docsrs-cli schema --cmd completions --json
docsrs-cli schema --cmd error --json
docsrs-cli schema --cmd dry-run --json
docsrs-cli schema --cmd agent-surface --json
docsrs-cli schema --cmd all --json docsrs-cli version --json
docsrs-cli doctor --json
```
- Ask for the specific name, not the umbrella: `--cmd config-show` answers with the shape `config show` really emits
- The umbrella names `cache` and `config` describe the whole family, so they carry every variant at once
## How To Generate Shell Completions
- Problem: install completion scripts for your shell
```bash
docsrs-cli completions bash
docsrs-cli completions zsh
docsrs-cli completions fish
docsrs-cli completions elvish
docsrs-cli completions power-shell
docsrs-cli completions powershell
docsrs-cli completions bash --json
```
## How To Work Offline or Without Network Side Effects
- Problem: plan URLs without opening sockets
```bash
docsrs-cli --dry-run search-crates serde --json
docsrs-cli --dry-run readme serde --json
docsrs-cli --dry-run get-item tokio fn task::spawn --json
docsrs-cli --dry-run search-in-crate reqwest Client --json
```
## How To Manage Cache and Config
- Problem: inspect storage health and reset local state
```bash
docsrs-cli cache stats --json
docsrs-cli cache clear --yes --json
docsrs-cli config path --json
docsrs-cli config show --json
docsrs-cli config init --json
docsrs-cli config init --force --yes --json
```
## How To Audit Readiness Before a Batch
- Problem: fail closed before many agent turns
```bash
docsrs-cli doctor --json
docsrs-cli doctor --online --json
docsrs-cli --config-dir /tmp/docsrs-audit/config --cache-dir /tmp/docsrs-audit/cache config init --json
docsrs-cli --config-dir /tmp/docsrs-audit/config --cache-dir /tmp/docsrs-audit/cache doctor --json
docsrs-cli --config-dir /tmp/docsrs-audit/config --cache-dir /tmp/docsrs-audit/cache doctor --online --json
```
## How To Cover Every Top-Level Command Once
- Problem: smoke the full command surface in one checklist
```bash
docsrs-cli search-crates serde --json
docsrs-cli readme serde --json
docsrs-cli get-item serde trait Serialize --json
docsrs-cli get-item tokio method runtime::Runtime::new --json
docsrs-cli search-in-crate serde Serialize --match prefix --json
docsrs-cli version --json
docsrs-cli doctor --json
docsrs-cli doctor --online --json
docsrs-cli commands --json
docsrs-cli schema --cmd get-item --json
docsrs-cli completions bash >/dev/null
docsrs-cli cache path --json
docsrs-cli cache stats --json
docsrs-cli cache clear --yes --json
docsrs-cli config path --json
docsrs-cli config show --json
docsrs-cli config init --json
```