docsrs-cli
Fetch crates.io and docs.rs docs in one shot for agents.
What is it
- One-shot stdin/stdout CLI for crates.io search and docs.rs item pages
- Lifecycle is always BORN, EXECUTE, FINALIZE, DIE
- No daemon, no sticky session, no product telemetry
- JSON auto-selects when stdout is not a TTY
- Public HTTP only against an allowlist of docs hosts
- Current product line is 0.1.x
The Pain
- Agents scrape HTML by hand and burn tokens on noise
- Browser tabs and curl pipelines do not form a stable contract
- Sticky MCP servers keep sockets open between turns
Why
- Stable JSON envelopes on stdout for every command
- Markdown human path when you force
--format markdown - XDG disk cache with TTL and soft budget plus
data.cache_hit - Polite rate limits, full-jitter HTTP retry, cancel-safe shutdown
- Exit codes agents can branch on without parsing prose
- Ranked in-crate match modes stop noisy false positives
Superpowers
search-cratesagainst crates.io with pagination, sort, and--page-token--page-tokenechoesquery/page/per_page/sortfrom the effective URLreadmefor the docs.rs crate overview docblock withresolved_versionget-itemfor typed rustdoc pages including associated methods- Method fetch scopes markdown and may set
data.extractiontomethodoritem_page search-in-crateoverall.htmlwith--match exact|prefix|substring--suggestranks exact → prefix → substring → edit-distance on get-item 404item_pathaccepts hyphens and normalizes to underscores for rustc paths- Markdown scrub removes rustdoc chrome (
§, “Copy item path”) - Body over cap is
error.kind=budget(exit 74,retryable=false) - stdlib fetch for
std,core, andallocvia doc.rust-lang.org commands,schema,doctor,versionfor agent discoverydoctor --onlinefor opt-in DNS probes to crates.io and docs.rsdoctortop-levelokmirrorsdata.okcacheandconfigfor XDG maintenance without secrets
What's New in 0.1.2
- Effective-URL echo for
--page-token(and matching dry-runplanned_params) - Method-scoped extraction with optional
data.extraction - Non-retryable local body budget errors (
kind=budget) - Cascade
--suggest, hyphen path normalize, rustdoc chrome scrub - Fail-closed
--timeout 0/--connect-timeout 0(exit 65) - Human smoke ritual:
scripts/smoke-live.sh(not CI) - Full notes under CHANGELOG.md section
[0.1.2]
Quick Start
Installation
- From crates.io:
cargo install docsrs-cli --locked - From a local checkout:
cargo install --path . --locked - MSRV is Rust 1.88
- No Cargo feature flags exist in this package
Usage
- Pass
--jsonor pipe stdout for the agent envelope - Force human output with
--format markdownor--format text - Plan URLs without network using
--dry-run - Raise wall-clock budget with
--timeout <seconds> - Disable disk cache with
--no-cache - Product knobs use CLI flags or XDG
config.toml, never product env vars
Commands
- Full surface has 11 top-level commands
search-crates [query] [--page N] [--per-page N] [--sort KIND] [--page-token TOKEN]- Query may be omitted when
--page-tokencarries a full query string --pageconflicts with--page-token--sortacceptsrelevance,downloads,recent-downloads,recent-updates,new,alphabeticalreadme <crate> [--crate-version V]— docs.rs crate overview docblockget-item <crate> <item_type> <item_path> [--crate-version V] [--suggest]item_typeacceptsmodule,struct,trait,enum,union,fn/function/method,type,const/constant,static,macro,attr/attribute,derivemethodis an alias offnfor associated methods- Associated methods resolve to parent type pages with
#method.nameanditem_name item_pathaccepts::or/separators and optional crate prefix--suggeston get-item 404 lists nearby symbols fromall.htmlsearch-in-crate <crate> [query] [--crate-version V] [--item-type K] [--limit N] [--match MODE]--matchacceptsexact,prefix(default),substring- Empty
querylists classified items up to--limit(clamped to 1000) - Hits may include
scorewhen a query is present version— binary versiondoctor— local TLS, paths, concurrency, and retry readinessdoctor --online— also probes crates.io and docs.rs DNScommands— full command tree for agentsschema --cmd <name>— JSON Schema for a command payload- Schema targets:
search-crates,readme,get-item,search-in-crate,version,doctor,commands,schema,completions,error,dry-run,cache,config completions <shell>— raw shell script by default; JSON only with explicit--json- Shells:
bash,zsh,fish,elvish,power-shell(powershellalias) cache stats— report entry count, bytes, and budgetcache clear— delete cached HTTP bodiesconfig path— print resolved config/cache dirs and winning layerconfig show— print effective runtime configurationconfig init [--force]— create defaultconfig.toml
JSON contract highlights
- Success envelope:
schema_version,ok,command,data,duration_ms - Network payloads use canonical
crate_name(nevercrate) - Network payloads expose
cache_hitfor local disk cache only get-itemexposesitem_name, optionalresolved_version, optionalextractionreadmeexposes optionalresolved_version(stdlib channel isstable)search-in-crateechoesmatch_modeand optionalitem_typesearch-cratespagination tokens live underdata.meta.next_page/prev_page- After
--page-token, echoedquery/page/per_page/sortmatch the effective URL - Failure envelopes expose
error.kindanderror.retryable(never retrykind=budget)
Environment Variables
DOCSRS_CLI_HOME— sandbox root for config and cache (tests / isolation)DOCSRS_CLI_CONFIG_DIR/DOCSRS_CLI_CACHE_DIR— path overrides only- Product knobs (timeout, UA, cache TTL, retries, concurrency, lang) are not read from
DOCSRS_CLI_*env at runtime - Use CLI flags and XDG
config.tomlfor product settings RUST_LOG— tracing filter (stderr diagnostics only; not product telemetry)NO_COLOR/CLICOLOR_FORCE— diagnostics only
Integration Patterns
- Agent subprocess:
docsrs-cli get-item serde trait Serialize --json - Method fetch:
docsrs-cli get-item tokio fn runtime::Runtime::new --json - Ranked symbols:
docsrs-cli search-in-crate serde Serialize --match prefix --json - Paginate: read
meta.next_pagethendocsrs-cli search-crates --page-token '...' --json - Discovery first:
docsrs-cli commands --jsonthenschema --cmd get-item --json - Offline plan:
docsrs-cli --dry-run readme tokio --json - See INTEGRATIONS.md and docs/AGENTS.md
Performance
- One primary GET per command in the happy path
- Multi-thread Tokio runtime with Semaphore concurrency budget
spawn_blockingfor large HTML parse work- Disk cache avoids repeat downloads within TTL
- Warm cache responses set
data.cache_hitto true
Memory Requirements
- Default body cap is 10 MiB per response
- Default output cap is 2 MiB per emission
- Default disk cache budget is 256 MiB soft
- Raise caps only with explicit CLI flags or XDG
config.toml, never above hard ceilings
Troubleshooting FAQ
- Exit
65means invalid input (including explicit--timeout 0/--connect-timeout 0) - Exit
66means the crate or item was not found - Use
get-item ... --suggestto list nearby symbols after a 404 - Exit
69means rate limit or temporary upstream outage (retryable) - Exit
74witherror.kind=networkmeans transport failure; retry with backoff - Exit
74witherror.kind=budgetmeans local body cap; do not retry — raise--max-body-bytes - Always read
error.retryablebefore retrying any non-zero exit - Exit
78means local config or path readiness failed - Exit
124means wall-clock timeout - Run
docsrs-cli doctor --jsonbefore blaming the network - Treat doctor healthy only when top-level
okanddata.okare both true - Run
docsrs-cli doctor --online --jsonto probe crates.io and docs.rs DNS - Noisy search hits: switch from
--match substringtoprefixorexact - Hyphenated paths: pass
async-traitsegments; the CLI normalizes toasync_trait
Documentation Map
Contributing
- Read CONTRIBUTING.md
- Follow the Code of Conduct
Security
- Read SECURITY.md
- Report issues privately to daniloaguiarbr@proton.me
Changelog
- See CHANGELOG.md for version history
- Current release notes for 0.1.2 live under
[0.1.2]
License
- Dual-licensed under MIT or Apache-2.0
- See LICENSE, LICENSE-MIT, and LICENSE-APACHE